> ## 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. # Submit representment plan evidences > Confirm the evidence for a dispute's representment plan and generate the written representment sections, returned with a timeline of key events. ## OpenAPI ````yaml https://cdn.payrails.io/docs/api/openapi.min.json post /dispute/disputes/{disputeId}/evidences/submit-plan openapi: 3.2.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: Get started summary: Get started kind: nav - name: Workflow summary: Workflow kind: nav - name: Payment summary: Payment kind: nav - name: Provider summary: Provider kind: nav - name: Merchant summary: Merchant kind: nav - name: Vault summary: Vault kind: nav - name: Analytics summary: Analytics kind: nav - name: Reporting summary: Reporting kind: nav - name: Reconciliation summary: Reconciliation kind: nav - name: Dispute summary: Dispute kind: nav - name: 3D Secure description: Operations to monitor 3DS operations. parent: Payment - 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. parent: Workflow - name: API Logs description: API Logs. parent: Payment - name: Apple Pay description: >- Register and list a merchant's Apple Pay web domains. No merchant-owned certificate is needed — Payrails is registered with Apple as a payment platform integrator. parent: Merchant - 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. parent: Get started - name: BIN Lookup description: >- Operations related to getting information about a card by its BIN (or IIN). parent: Payment - name: Client description: Endpoints used by our client-side SDK. parent: Get started - name: Disputes description: Operations to managing disputes. parent: Dispute - 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. parent: Merchant - 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. parent: Workflow - name: Files description: Operations related to files processing parent: Analytics - 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. parent: Payment - 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. parent: Merchant - 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. parent: Payment - 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). parent: Payment - 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. parent: Payment - name: Payouts description: Payouts are money movements paid to an external party. - name: Provider Configs description: Operations related to managing configurations for Providers. parent: Provider - name: Providers description: Operations related to managing Providers. parent: Provider - name: Reconciliation Records description: >- Operations to retrieve reconciliation record aggregates, transactions, and reconciliation metadata. parent: Reconciliation - name: Report Runs description: Operations to generate and retrieve report runs. parent: Reporting - name: Reports description: Operations to see available reports. parent: Reporting - name: Rulesets description: Operations related to managing Rulesets. parent: Merchant - name: SSO Connections description: Operations related to managing SSO identity provider connections. parent: Get started - name: Vault Display SDK description: Operations related to DisplaySDK. parent: Vault - name: Vault Instant Proxy description: Operations related to Instant Proxy API requests. parent: Vault - name: Vault Proxy Connections description: Operations related to managing token connections. parent: Vault - name: Vault Public Encryption description: Public endpoints related to encryption. parent: Vault - name: Vault Records and Aliases description: Operations related to managing records and aliases. parent: Vault - 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. parent: Workflow - name: Workspaces description: Operations related to managing workspaces. parent: Merchant paths: /dispute/disputes/{disputeId}/evidences/submit-plan: post: tags: - Disputes summary: Submit representment plan evidences description: >- Confirm your evidence selections for the representment plan and trigger generation of the written representment sections. Returns the generated sections along with a timeline of key events for review. operationId: submitDisputeRepresentmentPlanEvidences parameters: - name: x-idempotency-key in: header description: > Idempotency key to be used. Sending again the same key would return the same result without re-executing the update. required: true schema: type: string format: uuid example: 91874e4d-81e9-4486-aee4-ee1de84da890 - name: disputeId in: path description: Identifier of the resource in Payrails. required: true schema: type: string format: uuid example: d5454c2f-ae5e-44f3-8edf-f6dad64f005f requestBody: required: true content: application/json: schema: type: object required: - evidences properties: selectedDefenseReasonCode: type: string description: >- The provider reason code the merchant wants to defend with. If omitted, the LLM-suggested code from plan generation remains in effect. evidences: type: array minItems: 1 description: >- List of selected representment plan evidence items and target positions. Each position must be unique. items: type: object required: - evidenceId - position properties: evidenceId: description: >- Unique identifier of an uploaded evidence linked to this dispute. type: string format: uuid position: description: >- Target representment plan evidence position to associate with evidenceId. type: integer minimum: 0 labels: description: >- Labels to assign to this evidence for the dispute, used to categorise the document during representment. type: array items: type: string userPrompt: type: string description: >- Additional user prompt to generate representment sections. If not provided, the system will use a default prompt. responses: '200': description: Evidence selections saved and representment sections generated. content: application/json: schema: type: object required: - representmentPlan - representmentSections properties: representmentPlan: description: >- Updated representment plan after selected evidences were stored. 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: >- Generated ordered representment sections based on selected evidences (Timeline sections excluded). 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 timeline: description: >- Deserialized timeline events extracted from the Timeline section, when present. type: array items: type: object required: - date - message properties: date: description: >- Date of the timeline event in ISO 8601 format (YYYY-MM-DD). type: string format: date message: description: >- Concise plain-text description of the timeline event (1-2 sentences, no HTML). type: string '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: Forbidden. 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 '409': description: Conflict. 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.conflict detail: >- The request operation is not allowed due to a conflict with the current state of the resource docUrl: >- https://docs.payrails.com/docs/resources/error-codes#requestconflict '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 '500': description: Internal Server Error. 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: internal detail: An internal error occurred docUrl: >- https://docs.payrails.com/docs/resources/error-codes#internal security: - BearerToken: - disputeevidences:create 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 - [Generate representment plan](/reference/generatedisputerepresentmentplan.md) - [Regenerate representment plan](/reference/regeneratedisputerepresentmentplan.md) - [Generate representment PDF](/reference/generatedisputerepresentmentpdf.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.