> ## Documentation Index > Fetch the complete documentation index at: https://docs.payrails.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. > Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. > Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. > Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. > Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. > Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. > Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. # Search & list Disputes > Search and list disputes in your workspace. Use the available filters to narrow results by status, payment, provider, date range, and more. ## OpenAPI ````yaml https://cdn.payrails.io/docs/api/openapi.min.json get /dispute/disputes openapi: 3.1.0 info: version: 1.3.15 title: Payrails API Reference contact: name: Payrails url: https://www.payrails.com email: tech@payrails.com license: name: Payrails GmbH url: https://www.payrails.com/ description: > --- Payrails provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. servers: - url: https://api.staging.payrails.io description: Payrails environment. security: - ApiKey: [] tags: - name: 3D Secure description: Operations to monitor 3DS operations. - name: Actions description: >- A workflow execution action is a predefined interaction that can be triggered to change the state of the workflow execution. For example authorizing or refunding a payment. - name: API Logs description: API Logs. - name: Authentication description: >- Payrails API is secured via [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) industry-standard protocol for authorization. Server-side requests are authenticated using a [Bearer Token](https://datatracker.ietf.org/doc/html/rfc6750) in the request `Authorization` header. - name: BIN Lookup description: >- Operations related to getting information about a card by its BIN (or IIN). - name: Client description: Endpoints used by our client-side SDK. - name: Disputes description: Operations to managing disputes. - name: Drop-in Links description: >- Create and manage drop-in payment links that can be shared with payers. Drop-in links support full or partial payments, define the total amount and expiration, and return a public URL that merchants can send to customers. - name: Executions description: >- A workflow execution is an act of performing a set of tasks that are defined in the [Workflow](/api-reference/reference/#operation/listDefaultWorkflows) such as accepting payments. - name: Files description: Operations related to files processing - name: Fraud Checks description: >- A Fraud check Payrails is a collection of operations over time, that is created by a workflow execution and followed by the workflow actions. In this section, you can list all the fraud entities or a single one to learn about the details of involved instruments, providers, statuses, decisions and more. - name: Holders description: >- A Holder is a group of accounts that belong together with specific criteria, linked to their payment instruments and identities. For example, it can represent a digital wallet for a person, where they store balance that they top up, refunded orders, referral bonuses, etc. - name: Instrument Tokens description: >- Tokens are representations of our payment instruments in external providers. One payment instrument can have many tokens, because we keep the mapping in each external provider that knows about it. For example, the same real life card can have a token in our Vault, but also in Adyen and Checkout PSPs. - name: Instruments description: >- Payment instruments are specific instances of a payment method that belong to the holder executing the workflow. They can be a previously stored card, a new card that was typed in a form, a phone number, an IBAN, or some way to fetch an account in a provider (like PayPal or AliPay). - name: Payments description: >- A [Payment](/guides/whats-payrails/payments/) in Payrails is a collection of operations over time, that is created by a workflow execution and followed by the workflow actions. In this section, you can list all the payments or a single one to learn about the details of involved payment methods, instruments, providers, statuses and more. - name: Payouts description: Payouts are money movements paid to an external party. - name: Provider Configs description: Operations related to managing configurations for Providers. - name: Providers description: Operations related to managing Providers. - name: Reconciliation Records description: >- Operations to retrieve reconciliation record aggregates, transactions, and reconciliation metadata. - name: Report Runs description: Operations to generate and retrieve report runs. - name: Reports description: Operations to see available reports. - name: Rulesets description: Operations related to managing Rulesets. - name: SSO Connections description: Operations related to managing SSO identity provider connections. - name: Vault Display SDK description: Operations related to DisplaySDK. - name: Vault Instant Proxy description: Operations related to Instant Proxy API requests. - name: Vault Proxy Connections description: Operations related to managing token connections. - name: Vault Public Encryption description: Public endpoints related to encryption. - name: Vault Records and Aliases description: Operations related to managing records and aliases. - name: Workflows description: >- Any operation in Payrails is defined and executed with a [Workflow](/guides/whats-payrails/workflow/) that is configured for a particular use-case of the merchant. The workflow configurations support versioning. - name: Workspaces description: Operations related to managing workspaces. paths: /dispute/disputes: get: tags: - Disputes summary: Search & list Disputes description: >- Search and list disputes in your workspace. Use the available filters to narrow results by status, payment, provider, date range, and more. operationId: listDisputes parameters: - name: filter[id] in: query schema: type: string description: Filter for a list of disputes by ID. - name: filter[providerId] in: query schema: type: string description: Filter for a list of disputes by provider ID. - name: filter[providerConfigId] in: query schema: type: string description: Filter for a list of disputes by provider config ID. - name: filter[providerReference] in: query schema: type: string description: Filter for a list of disputes by provider reference. - name: filter[paymentId] in: query schema: type: string description: Filter for a list of disputes by payment ID. - name: filter[paymentProviderReference] in: query schema: type: string description: Filter for a list of disputes by payment provider reference. - name: filter[holderReference] in: query schema: type: string description: Filter for a list of disputes by holder reference. - name: filter[customerEmail] in: query schema: type: string description: Filter for a list of disputes by customer email. - name: filter[stage] in: query schema: type: string description: Filter for a list of disputes by stage. - name: filter[defenseStatus] in: query schema: type: string description: Filter for a list of disputes by defense status. - name: filter[chargebackStatus] in: query schema: type: string description: Filter for a list of disputes by chargeback status. - name: filter[channel] in: query schema: type: string description: >- Filter for a list of disputes by the channel the customer used to raise them. - name: filter[assignedToUserEmail] in: query schema: type: string description: Filter for a list of disputes by assigned to user email. - name: filter[defensePeriodExpiresAt] in: query schema: type: string format: date-time description: Filter for a list of disputes by defense period expiration date. - name: filter[reason] in: query schema: type: string description: Filter for a list of disputes by reason. - name: filter[reasonCode] in: query schema: type: string description: Filter for a list of disputes by reason code. - name: filter[providerCreatedAt] in: query schema: type: string description: >- Filter for a list of disputes by provider created at date. Accepts ISO 8601 date-time values or range expressions (e.g. `[2024-01-01T00:00:00Z,2024-12-31T23:59:59Z)`). - name: filter[merchantReference] in: query schema: type: string description: Filter for a list of disputes by merchant reference. - name: filter[executionId] in: query schema: type: string description: Filter for a list of disputes by execution ID. - name: filter[containsall][tags] in: query schema: type: string description: > Filter disputes by attached tag slugs. Accepts a comma-separated list of tag slugs (e.g. `fraud,bin_list`). Only disputes that have **all** of the specified tags attached are returned. - name: sort[defensePeriodExpiresAt] in: query schema: type: string enum: - asc - desc description: > Order the list by defense deadline. `asc` returns the soonest-expiring disputes first, `desc` the furthest out; disputes with no deadline are returned last either way. Exactly one `sort[field]` parameter may be given per request: a second one, a repeated one, a bare `sort=field`, or a direction other than `asc` or `desc` all return 400. The `last` link resolves in either direction, and the page it returns is the one holding the disputes with no deadline. - name: sort[providerCreatedAt] in: query schema: type: string enum: - asc - desc description: > Order the list by the date the provider raised the dispute. This is the default ordering, descending, when no `sort[field]` parameter is given. Disputes with no such date are returned last either way. The one-term limit and the `last` link behaviour apply here too, as described on `sort[defensePeriodExpiresAt]`. - name: includeSummary in: query schema: type: boolean default: false description: >- Boolean indicating if the disputes summary should be included in the response. - name: includePayment in: query schema: type: boolean default: false description: >- Boolean indicating if the disputes payment should be included in the response. - name: includeInstrument in: query schema: type: boolean default: false description: >- Boolean indicating if the disputes instrument should be included in the response. - name: includeRepresentmentPlanStatus in: query schema: type: boolean default: false description: >- Boolean indicating if the representment plan status should be included in the response. - name: includeUserEmail in: query schema: type: boolean default: false description: >- Boolean indicating if the assigned user email and username should be included in the response. responses: '200': description: Success. content: application/json: schema: type: object properties: links: required: - self properties: self: type: string prev: type: string next: type: string first: type: string last: type: string results: type: array items: type: object required: - id - createdAt - updatedAt - providerConfigId - providerId - providerReference - stage properties: id: description: Unique identifier of the Dispute in Payrails. format: uuid type: string createdAt: description: >- Date and time when the Dispute was created in Payrails. format: date-time type: string updatedAt: description: >- Date and time when the Dispute was last updated in Payrails. format: date-time type: string amount: type: object required: - value - currency properties: value: type: string pattern: '[0-9]+(\.[0-9]+)?' example: '12.50' description: >- Decimal amount of the major currency unit. Can be any precision. currency: type: string pattern: ^[A-Z]{3}$ example: EUR description: ISO 3-letter currency code. description: >- Amount of the Dispute. May differ from amount of Payment. applicableDefenseReasons: description: List of reasons codes used when defending a Dispute. type: array items: type: object required: - providerReasonCode properties: providerReasonCode: description: Defense reason code provided by Provider. type: string evidenceTypes: type: array items: type: object required: - providerTypeCode properties: providerTypeCode: description: >- Code of the type of evidence provided by Provider. type: string assignedToUserId: type: string format: uuid assignedToUserEmail: description: >- Email of the user currently assigned to this dispute. Only present when includeUserEmail=true and a user is assigned. type: string channel: type: string enum: - Provider - Issuer - Alert - Unknown description: >- Channel the customer used to raise the dispute. Not every provider reports a channel, and the field is only populated on disputes received after it was introduced. It is therefore absent on many disputes, and absence says nothing about how the dispute was raised — do not read a missing `channel` as the absence of an issuer chargeback. - `Provider`: the customer raised the dispute with the payment provider directly, without involving their bank. - `Issuer`: the customer went to their card issuer or bank, so the dispute is a card chargeback. - `Alert`: the dispute arrived as a pre-chargeback alert, and no chargeback has been raised yet. - `Unknown`: the Provider reported a channel that Payrails does not recognize. chargebackStatus: type: string enum: - Incoming - Executed - Reversed - SecondChargeback - IssuerReponseTimeframeExpired - ArbitrationReversed description: Status of the chargeback. defenseStatus: type: string enum: - NotDefendable - Undefended - ReadyToSubmit - Submitted - Failed - UnderReview - Won - Lost - Accepted - Resolved - Unknown description: Status of the defense. defensePeriodExpiresAt: description: >- Date and time when the Dispute defense period expires. format: date-time type: string providerId: description: >- Unique identifier of the Provider that was used to process the Dispute. format: uuid type: string providerConfigId: description: >- Unique identifier of the merchant-specific Provider Configuration that was used to process the Dispute. This can include the set of credentials used, the merchant account, country, vertical, etc. format: uuid type: string providerReference: description: Unique identifier of the Dispute in the Provider. type: string providerCreatedAt: description: >- Date and time when the Dispute was created in the Provider. Only present if informed by Provider. format: date-time type: string merchantReference: description: >- Merchant-supplied reference for the payment that originated the Dispute (e.g. an order ID). Populated from the PSP notification for Adyen, PayPal, and Checkout.com disputes, or from the linked Payment for other providers. Omitted when not available. type: string paymentId: description: >- Unique identifier in Payrails of the Payment that originated the Dispute. Only available if the Payment was created via Payrails. When handling Disputes related to Payments created outside Payrails, this field will be omitted. format: uuid type: string workspaceId: description: Workspace ID that the Dispute belongs to. format: uuid type: string executionId: description: >- Unique identifier of the workflow execution that manages this Dispute's lifecycle in Payrails. Present once the dispute-management workflow has been started for the Dispute; omitted otherwise. type: string reason: type: string description: >- Human-readable description of why the dispute was raised. reasonCode: type: string description: >- Provider-specific reason code for the dispute, when supplied by the Provider. schemeReasonCode: type: string description: >- Card-scheme reason code for the dispute, when supplied by the Provider. stage: type: string enum: - Created - FraudReport - Retrieval - Chargeback - PreArbitration - Arbitration - Unknown description: Stage of the dispute. issuerComments: description: >- Free-text comments from the issuer or provider about the dispute, keyed by source. Populated for Adyen, Nuvei, PayPal, and Klarna disputes. Not provided for Checkout.com, Stripe, or Revolut. Omitted when not available. additionalProperties: type: string type: object liabilityShifted: description: >- Indicates whether liability has shifted away from the merchant, as determined by the Provider or by 3DS authentication data. When true, the issuer bears the chargeback liability. Null if not yet determined. type: boolean nullable: true payment: type: object required: - status properties: id: type: string format: uuid description: >- Unique identifier of the Payment in Payrails. Omitted for Disputes on Payments that were not created via Payrails. status: type: string description: >- Current status of the Payment in Payrails. More information can be found [here](https://docs.payrails.com/docs/resources/payments/payment-status). enum: - Created - Pending - Unknown - Failed - Expired - Preauthorized - Authorized - Canceled - Captured - Refunded createdAt: type: string format: date-time description: >- Exact date and time when the Payment was created. Possibly differs slightly from the date in the PSP. providerId: type: string format: uuid description: >- Unique identifier of the Provider that was used to process the Payment. providerName: type: string description: >- Name of the Provider that was used to process the Payment, e.g. Adyen, Checkout, Stripe. providerDisplayName: type: string description: >- Display name of the Provider that was used to process the Payment. providerReference: type: string description: >- Unique identifier of the Payment in an external system, e.g. PSP. providerConfigId: type: string format: uuid description: >- Unique identifier of the merchant-specific Provider Configuration that was used to process the Payment. This can include the set of credentials used, the merchant account, country, vertical, etc. providerIntegrationType: type: string description: >- Type of integration used to process the payment (in case the payment provider supports multiple). paymentMethodType: type: string description: >- Type of payment method used to process the payment. holderId: type: string format: uuid description: >- Unique identifier of the Holder that is involved in the Payment. holderReference: type: string description: >- Merchant-provided reference of the Holder involved in the Payment. amount: type: object required: - value - currency properties: value: type: string pattern: '[0-9]+(\.[0-9]+)?' example: '12.50' description: >- Decimal amount of the major currency unit. Can be any precision. currency: type: string pattern: ^[A-Z]{3}$ example: EUR description: ISO 3-letter currency code. description: Amount of the Payment. merchantReference: type: string description: >- Merchant-provided reference for the Execution. Commonly, the identifier of the order on the Merchant's system. workspaceId: type: string format: uuid description: Workspace ID that the Payment belongs to. instrument: type: object required: - id - holderId - paymentMethod - status - createdAt - updatedAt properties: id: type: string format: uuid description: Id of the instrument. createdAt: type: string format: date-time description: >- Date and time when the Instrument was created in Payrails. updatedAt: type: string format: date-time description: When the Instrument was last updated. holderId: type: string format: uuid description: Unique identifier of the Holder in Payrails. paymentMethod: type: string description: Represents the payment method type. enum: - alexBankMa7fazty - applePay - audi2pay - bankAccount - card - 2c2p - vietQR - cibSmartWallet - easypaisa - etisalatCash - fawryMobileWallet - fawryPay - googlePay - jazzCash - nbePhoneCash - orangeCash - payPal - qnbEWallet - weCash - genericRedirect - alfa - konnect - eftPro - netBanking - upi - cashFreeWallet - paytmWallet - phonePe - iDeal - bancontact - klarnaPayLater - klarnaPayNow - klarnaPayOverTime - scalapay status: type: string description: Status of the instrument. enum: - created - deleted - enabled - disabled - transient displayName: type: string description: Instrument name suitable for display. description: type: string description: Description of the instrument. default: type: boolean description: >- True if this instrument is set as default for the holder. nullable: true merchantReference: type: string description: >- Merchant-provided reference for the instrument. fingerprint: type: string description: >- System-wide unique identifier of the Instrument. If two Holders have the same instrument stored, this value will be the same for both, but the instrument and token IDs will be different. Cannot be used for payments, should only be used for analytics and fraud prevention. futureUsage: type: string description: >- Represents the future usage to define the payment flows that the stored instrument will be used for. enum: - Subscription - CardOnFile - UnscheduledCardOnFile networkTransactionReference: type: string description: >- Identifier of the initial payment made with this instrument on the Networks, e.g. Mastercard Trace ID or Visa Transaction ID. transactionLinkId: type: string description: >- Mastercard Transaction Link Identifier (TLID) of the transaction series this instrument belongs to. Returned by the card network on the initial cardholder-initiated transaction and required on economically related merchant-initiated transactions, such as recurring payments and installments, when the series spans payment providers. data: description: >- Type-specific information about the instrument. anyOf: - title: Card type: object description: Data specific to a Card instrument. required: - network - bin - suffix properties: network: type: string description: Network of the instrument. enum: - unspecified - visa - visadankort - mastercard - amex - diners - discover - unionpay - unionpayuzcard - maestro - maestrobancontact - hipercard - jcb - jcblankapay - argencard - aura - belkart - bpfuelcard - cabal - carnet - cirrus - chjonesfuelcard - uzcard - codensa - dankort - dinacard - duet - ebt - eftpos - elo - euroshellfuelcard - gecapital - bc - hrgstore - humo - lankapay - lukoilfuelcard - bancontact - meeza - newday - mir - ourocard - pagobancomat - paypak - paypal - phhfuelcard - prostir - rupay - sbercard - sodexo - starrewards - cencosud - naranja - troy - uatp - ukfuelcard - verve - voyager - vpay - wex - cmi - atm - bankcard - localbrand - loyalty - privatelabel - fuelcard - redfuelcard - redliquidfuelcard preferredScheme: type: string description: Network of the instrument. enum: - unspecified - visa - visadankort - mastercard - amex - diners - discover - unionpay - unionpayuzcard - maestro - maestrobancontact - hipercard - jcb - jcblankapay - argencard - aura - belkart - bpfuelcard - cabal - carnet - cirrus - chjonesfuelcard - uzcard - codensa - dankort - dinacard - duet - ebt - eftpos - elo - euroshellfuelcard - gecapital - bc - hrgstore - humo - lankapay - lukoilfuelcard - bancontact - meeza - newday - mir - ourocard - pagobancomat - paypak - paypal - phhfuelcard - prostir - rupay - sbercard - sodexo - starrewards - cencosud - naranja - troy - uatp - ukfuelcard - verve - voyager - vpay - wex - cmi - atm - bankcard - localbrand - loyalty - privatelabel - fuelcard - redfuelcard - redliquidfuelcard bin: type: string minLength: 6 maxLength: 8 description: >- First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number). example: '416598' binLookup: description: >- Information about an issuer by the given BIN (or IIN). type: object required: - bin properties: bin: type: string minLength: 6 maxLength: 8 description: >- First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number). example: '416598' network: type: string description: Network of the instrument. enum: - unspecified - visa - visadankort - mastercard - amex - diners - discover - unionpay - unionpayuzcard - maestro - maestrobancontact - hipercard - jcb - jcblankapay - argencard - aura - belkart - bpfuelcard - cabal - carnet - cirrus - chjonesfuelcard - uzcard - codensa - dankort - dinacard - duet - ebt - eftpos - elo - euroshellfuelcard - gecapital - bc - hrgstore - humo - lankapay - lukoilfuelcard - bancontact - meeza - newday - mir - ourocard - pagobancomat - paypak - paypal - phhfuelcard - prostir - rupay - sbercard - sodexo - starrewards - cencosud - naranja - troy - uatp - ukfuelcard - verve - voyager - vpay - wex - cmi - atm - bankcard - localbrand - loyalty - privatelabel - fuelcard - redfuelcard - redliquidfuelcard localNetwork: description: >- Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact. type: string enum: - bancontact - cartesbancaires - dankort - mada issuer: type: string description: >- Name of the bank or institution that issued the card. issuerCountry: description: >- Country of the bank or institution that issued the card. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. segment: type: string description: >- Segment of the card, e.g. gold, black, business. type: type: string description: >- Type of the card, e.g. credit, debit, prepaid, gift. typeDetails: type: string description: >- More information about the card type, e.g. personal, commercial. isNetworkToken: type: boolean description: > Indicates whether the card credential represents a network token rather than a primary account number (PAN). isFlexCard: type: boolean description: > Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard. billingAddress: description: Billing Address of the instrument. type: object properties: street: type: string description: >- The name of the street of a postal address. doorNumber: type: string description: >- The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: >- The name of the suburb or area within a city. city: type: string description: >- The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: >- The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. suffix: type: string minLength: 4 maxLength: 4 description: Last digits of the Card number. expiryMonth: type: string minLength: 2 maxLength: 2 description: Expiry month of the Card. expiryYear: type: string minLength: 4 maxLength: 4 description: Expiry year of the Card. holderName: type: string description: Name of the owner of the Card. taxId: type: string description: >- Payer-provided tax identification number (e.g. CPF in Brazil) collected on the instrument. - title: BankAccount type: object description: >- Data specific to a BankAccount instrument. properties: holder: type: object description: >- The data structure for a holder's personal information. properties: firstName: type: string description: The first name of the account holder. lastName: type: string description: The last name of the account holder. companyName: type: string description: The company name for business holders. address: description: The address of the account holder. type: object properties: street: type: string description: >- The name of the street of a postal address. doorNumber: type: string description: >- The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: >- The name of the suburb or area within a city. city: type: string description: >- The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: >- The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. email: type: string format: email description: The email address of the account holder. dob: type: string format: date description: >- The date of birth of the account holder (YYYY-MM-DD). country: description: The country of the account holder. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. city: type: string description: The city of the account holder. type: type: string enum: - individual - corporate description: The type of account holder. bank: type: object description: >- The data structure for a bank's information. properties: name: type: string description: The name of the bank. branchCode: type: string description: The branch code of the bank. code: type: string description: The bank code. address: description: The address of the bank. type: object properties: street: type: string description: >- The name of the street of a postal address. doorNumber: type: string description: >- The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: >- The name of the suburb or area within a city. city: type: string description: >- The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: >- The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. swiftCode: type: string description: The SWIFT/BIC code of the bank. account: type: object description: >- The data structure for an account's information. properties: number: type: string description: The bank account number. iban: type: string description: >- The International Bank Account Number (IBAN). currency: type: string pattern: ^[A-Z]{3}$ example: USD description: ISO 3-letter currency code. country: description: The country of the account. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. type: type: string enum: - savings - current description: The type of bank account. - title: PayPal type: object description: Data specific to a PayPal instrument. properties: email: type: string description: Email of the PayPal account. payerId: type: string description: ID of the PayPal payer account. billingAddress: description: Billing Address of the instrument. type: object properties: street: type: string description: >- The name of the street of a postal address. doorNumber: type: string description: >- The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: >- The name of the suburb or area within a city. city: type: string description: >- The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: >- The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. - title: GooglePay type: object description: Data specific to a GooglePay instrument. allOf: - type: object required: - network - suffix properties: network: type: string description: Network of the instrument. enum: - unspecified - visa - visadankort - mastercard - amex - diners - discover - unionpay - unionpayuzcard - maestro - maestrobancontact - hipercard - jcb - jcblankapay - argencard - aura - belkart - bpfuelcard - cabal - carnet - cirrus - chjonesfuelcard - uzcard - codensa - dankort - dinacard - duet - ebt - eftpos - elo - euroshellfuelcard - gecapital - bc - hrgstore - humo - lankapay - lukoilfuelcard - bancontact - meeza - newday - mir - ourocard - pagobancomat - paypak - paypal - phhfuelcard - prostir - rupay - sbercard - sodexo - starrewards - cencosud - naranja - troy - uatp - ukfuelcard - verve - voyager - vpay - wex - cmi - atm - bankcard - localbrand - loyalty - privatelabel - fuelcard - redfuelcard - redliquidfuelcard networkDisplayName: type: string description: Display-friendly name of the network. binLookup: description: Information about an issuer. type: object properties: network: type: string description: Network of the instrument. enum: - unspecified - visa - visadankort - mastercard - amex - diners - discover - unionpay - unionpayuzcard - maestro - maestrobancontact - hipercard - jcb - jcblankapay - argencard - aura - belkart - bpfuelcard - cabal - carnet - cirrus - chjonesfuelcard - uzcard - codensa - dankort - dinacard - duet - ebt - eftpos - elo - euroshellfuelcard - gecapital - bc - hrgstore - humo - lankapay - lukoilfuelcard - bancontact - meeza - newday - mir - ourocard - pagobancomat - paypak - paypal - phhfuelcard - prostir - rupay - sbercard - sodexo - starrewards - cencosud - naranja - troy - uatp - ukfuelcard - verve - voyager - vpay - wex - cmi - atm - bankcard - localbrand - loyalty - privatelabel - fuelcard - redfuelcard - redliquidfuelcard localNetwork: description: >- Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact. type: string enum: - bancontact - cartesbancaires - dankort - mada issuer: type: string description: >- Name of the bank or institution that issued the card. issuerCountry: description: >- Country of the bank or institution that issued the card. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. segment: type: string description: >- Segment of the card, e.g. gold, black, business. type: type: string description: >- Type of the card, e.g. credit, debit, prepaid, gift. typeDetails: type: string description: >- More information about the card type, e.g. personal, commercial. isNetworkToken: type: boolean description: > Indicates whether the card credential represents a network token rather than a primary account number (PAN). isFlexCard: type: boolean description: > Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard. billingAddress: description: Billing Address of the instrument. type: object properties: street: type: string description: >- The name of the street of a postal address. doorNumber: type: string description: >- The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: >- The name of the suburb or area within a city. city: type: string description: >- The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: >- The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. shippingAddress: description: Shipping Address provided by the wallet. type: object properties: street: type: string description: >- The name of the street of a postal address. doorNumber: type: string description: >- The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: >- The name of the suburb or area within a city. city: type: string description: >- The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: >- The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. suffix: type: string minLength: 4 maxLength: 4 description: Last digits of the Card number. expiryMonth: type: string minLength: 2 maxLength: 2 description: Expiry month of the Card. expiryYear: type: string minLength: 4 maxLength: 4 description: Expiry year of the Card. paymentToken: type: string description: >- One-time payment token sent by client-side for execution of payment on backend. eci: type: string description: >- Payment System-specific value provided by the ACS to indicate the results of the attempt to authenticate the Cardholder. cardHolderAuthenticated: type: boolean description: >- Indicates that identification and verifications (ID&V) was performed on the returned payment credential. - type: object properties: googleMessageId: type: string description: >- Unique identifier for the Google Pay message. googleMessageExpirationId: type: string description: >- Expiration time for the Google Pay message. - title: ApplePay type: object description: Data specific to a ApplePay instrument. required: - network - suffix properties: network: type: string description: Network of the instrument. enum: - unspecified - visa - visadankort - mastercard - amex - diners - discover - unionpay - unionpayuzcard - maestro - maestrobancontact - hipercard - jcb - jcblankapay - argencard - aura - belkart - bpfuelcard - cabal - carnet - cirrus - chjonesfuelcard - uzcard - codensa - dankort - dinacard - duet - ebt - eftpos - elo - euroshellfuelcard - gecapital - bc - hrgstore - humo - lankapay - lukoilfuelcard - bancontact - meeza - newday - mir - ourocard - pagobancomat - paypak - paypal - phhfuelcard - prostir - rupay - sbercard - sodexo - starrewards - cencosud - naranja - troy - uatp - ukfuelcard - verve - voyager - vpay - wex - cmi - atm - bankcard - localbrand - loyalty - privatelabel - fuelcard - redfuelcard - redliquidfuelcard networkDisplayName: type: string description: Display-friendly name of the network. binLookup: description: Information about an issuer. type: object properties: network: type: string description: Network of the instrument. enum: - unspecified - visa - visadankort - mastercard - amex - diners - discover - unionpay - unionpayuzcard - maestro - maestrobancontact - hipercard - jcb - jcblankapay - argencard - aura - belkart - bpfuelcard - cabal - carnet - cirrus - chjonesfuelcard - uzcard - codensa - dankort - dinacard - duet - ebt - eftpos - elo - euroshellfuelcard - gecapital - bc - hrgstore - humo - lankapay - lukoilfuelcard - bancontact - meeza - newday - mir - ourocard - pagobancomat - paypak - paypal - phhfuelcard - prostir - rupay - sbercard - sodexo - starrewards - cencosud - naranja - troy - uatp - ukfuelcard - verve - voyager - vpay - wex - cmi - atm - bankcard - localbrand - loyalty - privatelabel - fuelcard - redfuelcard - redliquidfuelcard localNetwork: description: >- Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact. type: string enum: - bancontact - cartesbancaires - dankort - mada issuer: type: string description: >- Name of the bank or institution that issued the card. issuerCountry: description: >- Country of the bank or institution that issued the card. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. segment: type: string description: >- Segment of the card, e.g. gold, black, business. type: type: string description: >- Type of the card, e.g. credit, debit, prepaid, gift. typeDetails: type: string description: >- More information about the card type, e.g. personal, commercial. isNetworkToken: type: boolean description: > Indicates whether the card credential represents a network token rather than a primary account number (PAN). isFlexCard: type: boolean description: > Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard. billingAddress: description: Billing Address of the instrument. type: object properties: street: type: string description: >- The name of the street of a postal address. doorNumber: type: string description: >- The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: >- The name of the suburb or area within a city. city: type: string description: >- The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: >- The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. shippingAddress: description: Shipping Address provided by the wallet. type: object properties: street: type: string description: >- The name of the street of a postal address. doorNumber: type: string description: >- The number on the door, building, or room. complement: type: string description: >- Additional addressing information, 2nd line of postal address. area: type: string description: >- The name of the suburb or area within a city. city: type: string description: >- The name of the city of a postal address. postalCode: type: string description: The postal code. state: type: string description: >- The name of the state a postal address is in. country: description: The country where the address is in. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. latitude: type: number format: float description: >- Latitude of the address in the GPS coordinate system. longitude: type: number format: float description: >- Longitude of the address in the GPS coordinate system. phone: description: >- The phone to contact in the address (can be different that the customer's). type: object required: - number properties: countryCode: type: string pattern: ^\+?[0-9]+$ description: >- International prefix of the phone, if known separately. number: type: string pattern: ^[0-9]+$ description: >- The local number of the phone, such that `countryCode` + `number` can be dialed. alias: type: string description: Name of the address, e.g. home, work. name: type: string description: >- Name of the person to whom the address belongs to. lastName: type: string description: >- Last name of the person to whom the address belongs to. email: type: string description: >- Email of the person to whom the address belongs to. suffix: type: string minLength: 4 maxLength: 4 description: Last digits of the Card number. expiryMonth: type: string minLength: 2 maxLength: 2 description: Expiry month of the Card. expiryYear: type: string minLength: 4 maxLength: 4 description: Expiry year of the Card. paymentToken: type: string description: >- One-time payment token sent by client-side for execution of payment on backend. eci: type: string description: >- Payment System-specific value provided by the ACS to indicate the results of the attempt to authenticate the Cardholder. cardHolderAuthenticated: type: boolean description: >- Indicates that identification and verifications (ID&V) was performed on the returned payment credential. - title: DCB type: object description: Data specific to a DCB instrument. properties: msisdn: type: string description: >- Mobile number of the holder MSISDN Stands for Mobile Station International Subscriber Directory Number. msisdnTail: type: string description: >- Last 4 digits of the mobile number of the holder. country: description: Country of the holder. type: object required: - code properties: code: type: string description: ISO 3166-1 alpha-2 country code. pattern: ^[A-Z]{2}$ iso3: type: string description: >- ISO 3-letter country code. Returned by Payrails, but not interpreted in requests. pattern: ^[A-Z]{3}$ name: type: string description: >- The English name of the country. Returned by Payrails, but not interpreted in requests. carrierNetwork: type: string description: Carrier network of the msisdn. - title: MBWay type: object description: Data specific to an MB WAY instrument. properties: phone: type: object description: >- Mobile number the payer confirms MB WAY payments with. properties: countryCode: type: string description: >- International dialling code, digits only. example: '351' number: type: string description: National number, digits only. example: '912345678' description: >- Optionally included details about the instrument used for the payment. meta: type: object additionalProperties: true description: >- Metadata for the context of an execution. Includes Payrails-defined structures for most common fields used in workflows, but can also be extended by merchant or provider-specific fields. For more information, visit our [Meta Fields guide](https://docs.payrails.com/docs/orchestration/payment-acceptance/meta-fields). See [Meta](/reference/meta) for every field. evidences: description: List of evidences associated with this dispute. type: array items: type: object required: - id - createdAt - updatedAt properties: id: description: Unique identifier of the Dispute in Payrails. format: uuid type: string createdAt: description: >- Date and time when the Dispute was created in Payrails. format: date-time type: string updatedAt: description: >- Date and time when the Dispute was last updated in Payrails. format: date-time type: string displayTitle: description: >- Display title of the evidence, usually the file name. type: string status: type: string description: Status of the dispute evidence. enum: - Active - Inactive - Unknown provenance: type: string description: Provenance of the dispute evidence. enum: - Merchant - Payrails - Unknown contentType: description: MIME type of the evidence content. type: string contentLength: description: Size of the evidence content in bytes. type: integer payload: description: >- Inline JSON payload for inline-context evidences. Present only for evidences created from `inlineContexts`; omitted for file-backed evidence. type: object additionalProperties: true workspaceId: description: Workspace ID that the Dispute belongs to. format: uuid type: string labels: description: >- Labels assigned to this evidence for the dispute, used to categorise the document during representment. type: array items: type: string representmentPlan: description: Representment plan details for this dispute. type: object required: - disputeId - createdAt - updatedAt - status properties: disputeId: description: Unique identifier of the dispute in Payrails. format: uuid type: string providerResponseId: description: >- Provider response identifier for representment plan generation. type: string createdAt: description: >- Date and time when the representment plan was created in Payrails. format: date-time type: string updatedAt: description: >- Date and time when the representment plan was last updated in Payrails. format: date-time type: string status: type: string description: Status of the representment plan lifecycle. enum: - GeneratingPlan - PlanReady - StoringEvidences - LabelingEvidences - EvidencesReady - GeneratingRepresentment - RepresentmentReady - Submitted recommendation: description: >- Recommended action for the merchant (e.g. "defend" or "accept"). type: string rationale: description: Explanation supporting the recommendation. type: string defenseReasons: description: >- Defense reason codes with evidence options, grouped by provider reason code. type: array items: type: object required: - code - title - description - selected - options properties: code: description: Adyen defense document type code. type: string title: description: >- Human-readable name for this defense document type. type: string description: description: >- Explanation of what this defense document type covers. type: string selected: description: >- Whether this defense type is the recommended selection. type: boolean options: description: >- Evidence suggestions within this defense type. type: array items: type: object required: - position - title - description - required properties: position: description: >- Ordering position of this option within the defense type. type: integer slug: description: >- Machine-readable identifier for the evidence type. type: string title: description: Suggested title for this evidence. type: string description: description: >- Suggested details to include for this evidence. type: string required: description: >- Whether this evidence is mandatory for the defense. type: boolean evidenceInfo: description: >- Display metadata for the already-uploaded evidence file, present when evidenceId is set. type: object properties: displayTitle: description: >- Human-readable file name or title of the uploaded evidence. type: string contentType: description: MIME type of the uploaded evidence file. type: string contentLength: description: >- Size of the uploaded evidence file in bytes. type: integer representmentSections: description: Ordered representment sections for this dispute. type: array items: type: object required: - id - disputeId - createdAt - updatedAt - position - indent - sectionType properties: id: description: >- Unique identifier of the representment section in Payrails. format: uuid type: string disputeId: description: Unique identifier of the dispute in Payrails. format: uuid type: string createdAt: description: >- Date and time when the representment section was created in Payrails. format: date-time type: string updatedAt: description: >- Date and time when the representment section was last updated in Payrails. format: date-time type: string position: description: Position of the section in the representment. type: integer indent: description: >- Indentation level of the section in the representment. type: integer sectionType: type: string description: Type of representment section. enum: - Text - Picture - Timeline textSectionTitle: description: >- Title of the text section when sectionType is Text. type: string textSectionContent: description: >- Content of the text section when sectionType is Text. type: string pictureSectionEvidenceId: description: >- Linked evidence identifier when sectionType is Picture. format: uuid type: string pictureSectionLabel: description: >- Label for the picture section when sectionType is Picture. type: string pictureSectionEvidenceLinks: description: >- Links for downloading the picture section evidence file when sectionType is Picture. type: object properties: download: oneOf: - type: string - type: object description: Link related information. required: - href properties: href: type: string method: type: string description: >- HTTP method that should be used to call the `href`. enum: - GET - POST - PUT - PATCH - DELETE representmentPlanStatus: type: string description: Status of the representment plan lifecycle. enum: - GeneratingPlan - PlanReady - StoringEvidences - LabelingEvidences - EvidencesReady - GeneratingRepresentment - RepresentmentReady - Submitted tags: description: Tags attached to this dispute. type: array items: type: object required: - id - name - slug - color - type - typeId - cardinality - createdAt - updatedAt properties: id: description: Unique identifier of the Tag. type: string format: uuid workspaceId: description: >- Workspace the Tag belongs to. Null for org-level tags visible to all workspaces. type: string format: uuid nullable: true name: description: Human-readable display name of the Tag. type: string slug: description: URL-safe identifier derived from the Tag name. type: string color: description: >- Hex color code used to render the Tag (e.g. "#EF4444"). type: string description: description: Optional description of the Tag. type: string nullable: true type: description: >- Tag type slug. Determines cardinality and grouping (e.g. "merchant_status", "default"). type: string typeId: description: UUID of the tag_types row this tag belongs to. type: string format: uuid cardinality: description: > Whether multiple tags of this type can be attached to the same dispute at once. `single` means at most one tag of this type per dispute; `multi` allows many. type: string enum: - single - multi createdAt: description: Date and time when the Tag was created. type: string format: date-time updatedAt: description: Date and time when the Tag was last updated. type: string format: date-time deletedAt: description: >- Date and time when the Tag was soft-deleted. Null if active. type: string format: date-time nullable: true evidenceClassifications: description: >- AI classifications for the evidences associated with this dispute. Only present when includeEvidenceClassifications=true. type: array items: type: object required: - evidenceId - disputeId - status properties: evidenceId: description: >- Unique identifier of the evidence file that was classified. format: uuid type: string disputeId: description: >- Unique identifier of the dispute the evidence belongs to. format: uuid type: string status: description: Classification status. type: string enum: - classifying - classified - failed contentSummary: description: >- AI-generated summary of the evidence file content. type: string documentType: description: >- AI-inferred document type (e.g. "receipt", "shipping_label"). type: string provesStatement: description: >- AI-generated statement of what the evidence proves in the dispute context. type: string keyFacts: description: List of key facts extracted from the evidence. type: array items: type: string suggestedPlanMatches: description: >- Representment plan slots this evidence is suggested to fill, ordered by confidence. type: array items: type: object required: - defenseReasonCode - slug - position - rationale properties: defenseReasonCode: description: >- Defense reason code of the plan slot this evidence matches. type: string slug: description: >- Slug identifier of the matching plan evidence slot. type: string position: description: >- Position of the matching slot within the defense type. type: integer rationale: description: >- AI-generated explanation for why this evidence matches the slot. type: string providerResponseId: description: >- Identifier of the LLM provider response that produced this classification. type: string createdAt: description: >- Date and time when the classification was created. format: date-time type: string updatedAt: description: >- Date and time when the classification was last updated. format: date-time type: string summary: type: object nullable: true properties: countTotal: type: integer countUndefended: type: integer example: links: self: >- https://api.staging.payrails.io/dispute/disputes?page[after]=qf7pnbyfrr&page[size]=2 prev: >- https://api.staging.payrails.io/dispute/disputes?page[before]=hbe66nh8i8&page[size]=2 next: >- https://api.staging.payrails.io/dispute/disputes?page[after]=xk2h55zsy5&page[size]=2 first: >- https://api.staging.payrails.io/dispute/disputes?page[size]=2 last: >- https://api.staging.payrails.io/dispute/disputes?page[before]=9wkueqcavq&page[size]=2 results: - id: 56efbab8-53fa-5a14-9780-5c6d1aa80619 createdAt: '2026-01-13T16:20:05.740802Z' updatedAt: '2026-01-13T16:20:05.740802Z' workspaceId: 7f9f1882-a103-408d-ac96-46a7021e537a providerId: c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7 providerConfigId: 5eb08624-ecce-4cbc-9a8a-61d484172815 providerReference: P6KQKF9S8D77Z5V5 providerCreatedAt: '2026-01-13T16:20:04.102Z' payment: id: 9f3700b5-8cba-41e4-b36a-89e021b5bb02 createdAt: '2026-01-13T16:20:00.635896Z' providerId: c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7 providerName: adyen providerReference: XCCMR76F3RJMQJV5 providerConfigId: 5eb08624-ecce-4cbc-9a8a-61d484172815 workspaceId: 00000000-0000-0000-0000-000000000000 holderId: dbfe3474-71ca-4cdd-9fcb-d48b46a923df amount: value: '22.65' currency: EUR status: Captured instrumentId: b8eaa596-7660-4e18-8d42-8060671e0cd7 meta: clientContext: ipAddress: 217.110.239.132 origin: https://example.com osType: ios customer: country: code: DE lastName: Doe name: John reference: Holder-c5026204-ef0f-4d47-80b6-cd3b445210d6 order: reference: 57e06696-73f2-4c99-9dc3-d1619a4fb9db risk: allowNative3DS: false merchantReference: Merchant-cf0c5c0c-ce6b-413a-b4df-b95a30288327 paymentMethodType: card holderReference: Holder-c5026204-ef0f-4d47-80b6-cd3b445210d6 paymentId: 9f3700b5-8cba-41e4-b36a-89e021b5bb02 amount: value: '22.65' currency: EUR applicableDefenseReasons: - providerReasonCode: CreditOrCancellationPolicyProperlyDisclosed evidenceTypes: - providerTypeCode: DisclosureAtPointOfInteraction required: true reason: Services not provided/Merchandise not received] stage: Chargeback chargebackStatus: Incoming defenseStatus: Undefended - id: 1746359e-5674-5bc2-94ea-2efa5d415753 createdAt: '2026-01-13T16:20:11.699603Z' updatedAt: '2026-01-13T21:26:55.757444Z' workspaceId: 7f9f1882-a103-408d-ac96-46a7021e537a providerId: c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7 providerConfigId: 5eb08624-ecce-4cbc-9a8a-61d484172815 providerReference: W7LQKF9S8D77Z5V5 providerCreatedAt: '2026-01-13T16:20:10.283Z' payment: id: c585e119-8584-4136-b4f0-f4f08f00619f createdAt: '2026-01-13T16:20:06.660318Z' providerId: c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7 providerName: adyen providerReference: DNMZS76F3RJMQJV5 providerConfigId: 5eb08624-ecce-4cbc-9a8a-61d484172815 workspaceId: 00000000-0000-0000-0000-000000000000 holderId: 260fdd51-fc42-48b6-aca1-4eb573fa120b amount: value: '37.54' currency: EUR status: Captured instrumentId: f1ebd3bb-d813-4149-867e-6634b57fd417 meta: clientContext: ipAddress: 217.110.239.132 origin: https://example.com osType: ios customer: country: code: DE lastName: Doe name: John reference: Holder-537d8c47-36c3-4f29-88f7-cfc2f5e6ca65 order: reference: 547eb508-c5b6-4eb4-8439-57bbba0c143d risk: allowNative3DS: false merchantReference: Merchant-5f65c13d-5858-43f3-aa0d-5fb6218ac9fc paymentMethodType: card holderReference: Holder-537d8c47-36c3-4f29-88f7-cfc2f5e6ca65 paymentId: c585e119-8584-4136-b4f0-f4f08f00619f amount: value: '37.54' currency: EUR reason: Canceled recurring transaction stage: Chargeback chargebackStatus: Incoming defenseStatus: UnderReview '400': description: Bad Request. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: errors: - id: a24bc325-3929-4d9d-9c08-b3aa532685b7 code: request.malformed detail: The request has malformed syntax docUrl: >- https://docs.payrails.com/docs/resources/error-codes#requestmalformed '401': description: Unauthorized. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: errors: - id: a24bc325-3929-4d9d-9c08-b3aa532685b7 code: request.unauthorized detail: >- The request lacks necessary credentials to perform the specified action docUrl: >- https://docs.payrails.com/docs/resources/error-codes#requestunauthorized '403': description: Insufficient Scope. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: errors: - id: e7db22b3-914e-4975-928e-9edfb0885bea code: request.forbidden detail: >- The request credentials lack the required permissions to perform the specified action docUrl: >- https://docs.payrails.com/docs/resources/error-codes#requestforbidden '404': description: Not Found. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: errors: - id: a24bc325-3929-4d9d-9c08-b3aa532685b7 code: request.not-found detail: The requested resource was not found docUrl: >- https://docs.payrails.com/docs/resources/error-codes#requestnot-found '429': description: Too Many Requests. content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object description: >- Error struct that includes the error, cause, reason, and possible resolutions. Check the full documentation [here](https://docs.payrails.com/docs/resources/error-codes#error-structure). required: - id - code - detail properties: id: type: string format: uuid description: >- Unique identifier of the error. Please use this value when reporting an issue to our team, so we can help you faster. code: type: string description: >- Machine-friendly error code assigned to the error. Check the full list of possible values [here](https://docs.payrails.com/docs/resources/error-codes#list-of-error-codes). detail: type: string description: >- Human-readable description about the error, its cause, and resolution. docUrl: type: string description: >- Link to the specific documentation about this particular `code`. reason: type: object additionalProperties: true description: >- Metadata providing more details about the reason of the error. The structure of this object varies according to the `code`. example: errors: - id: a24bc325-3929-4d9d-9c08-b3aa532685b7 code: request.rate-limit detail: Too many requests docUrl: >- https://docs.payrails.com/docs/resources/error-codes#requestrate-limit security: - BearerToken: - disputes:list components: securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: > You can use your secret API key in the `x-api-key` header of your API requests for supported endpoints: `x-api-key: `. API keys are environment specific and should be securely guarded. You don't have your API key yet? Contact your Payrails account manager. BearerToken: type: http scheme: bearer bearerFormat: JWT description: > You can use an OAuth2 JWT bearer token in the `Authorization` header of your API requests for supported endpoints: `Authorization: Bearer `. These tokens are valid for 10 minutes and can be requested via the [access token endpoint](#operation/getOAuthToken) endpoint. ```` ## Related topics - [Search & list Dispute Alerts](/reference/listdisputealerts.md) - [Search & list Evidences](/reference/listdisputeevidences.md) - [Search & list providers](/reference/listproviders.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.