> ## Documentation Index > Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Mark a Transaction as Paid Externally > Record a pix or voucher sale that the buyer paid outside Pagou. Mark a pix or voucher transaction as **paid outside Pagou**, for example when the buyer paid by bank transfer after the charge expired. Use the transaction UUID returned as `id` in the path and authenticate with your company API key. The transaction moves to `paid_externally` for its full amount and Pagou runs the same delivery flow as a paid sale: the `transaction.paid` webhook (with `status: "paid_externally"`), the buyer confirmation e-mail and the tracking integrations. > [!WARNING] > > No money moves through Pagou for this sale: it creates no balance, settlement or sale fee, and it cannot be refunded or undone. Services your company has enabled, such as the buyer confirmation e-mail, are still charged as usual. Your integration must release orders on `paid_externally` as well as on `paid`. ## Which transactions can be marked * Payment method `pix` or `voucher`. * Status `pending` or `expired`, never paid before. Card, canceled, paid and refunded transactions return `422`. When the charge is still open, Pagou also tries to cancel it; the marking happens whether or not the cancellation succeeds. ## Request fields | Field | Type | Required | Constraints | | - | - | - | - | | `reason` | string | Yes | Trimmed, 1–500 chars, no ASCII control characters. | | `external_reference` | string \| null | No | Trimmed, 1–255 chars, no ASCII control characters. Your own reference for the outside payment. | ## Idempotency Calling the endpoint again for a transaction already marked returns its current state with `200` and has no other effect: no second webhook and no second e-mail. The `reason` and `external_reference` sent in the new call are ignored; the ones from the first marking are kept. ## If the buyer also pays through Pagou If the original charge is paid after the marking, the transaction moves to `paid` and the money follows the normal flow, with its fee. No second `transaction.paid` is sent, so the order is not released twice. Refunding that payment to the buyer follows the regular refund flow. ## Errors | Status | Meaning | | - | - | | `400` | Malformed request. | | `401` | Missing or invalid credentials. | | `404` | Transaction not found for this company. | | `422` | Validation failed, or the transaction cannot be marked (the `detail` says why). | | `429` | Rate limit exceeded. | ## Example ```bash theme={null} curl -X PUT "https://api.pagou.ai/v2/transactions/{id}/paid-externally" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "reason": "Paid by bank transfer", "external_reference": "TED-2026-10-27-0042" }' ``` The response carries the transaction in the same shape as [Get a Transaction](https://developer.pagou.ai/api-reference/transactions/get.md), with `status: "paid_externally"`. ## OpenAPI ````yaml api-reference/openapi-v2.json PUT /v2/transactions/{id}/paid-externally openapi: 3.1.0 info: title: Pagou API - v2 description: API for Pagou.ai Gateway version: 2.0.0 contact: name: Support url: https://pagou.ai email: support@pagou.ai servers: - url: https://api.pagou.ai description: Production server - url: https://api.sandbox.pagou.ai description: Sandbox server for testing security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] paths: /v2/transactions/{id}/paid-externally: put: tags: - Transactions summary: Mark a Transaction as Paid Externally description: >- Mark a pending or expired pix or boleto transaction as paid outside the platform. The transaction moves to `paid_externally` for its full amount and the `transaction.paid` webhook is sent with `status: "paid_externally"`. No balance, settlement or sale fee is created, and the marking cannot be undone or refunded. Calling it again on a transaction already marked returns its current state. Card, canceled, paid or refunded transactions return 422. operationId: putTransactionsByIdPaidExternally parameters: - schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: id required: true requestBody: required: true content: application/json: schema: type: object properties: reason: type: string minLength: 1 maxLength: 500 description: >- Why the sale is being marked as paid outside the platform. Required. example: Pago por transferência bancária external_reference: description: >- Your own reference for the outside payment, such as a bank transfer id. example: TED-2026-10-27-0042 nullable: true type: string minLength: 1 maxLength: 255 required: - reason responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean requestId: type: string data: type: object properties: id: description: >- Unique identifier of the transaction (numeric or UUID). type: string format: uuid amount: type: integer minimum: 100 maximum: 100000000 description: >- Total transaction amount in cents. When the buyer pays installment interest, `GET /v2/transactions/{id}` returns the amount before interest here, the same as `base_amount`. base_amount: description: >- Amount you sent, before any installment interest, in cents and in the transaction currency. type: integer minimum: 0 maximum: 9007199254740991 voucher: nullable: true type: object properties: barcode: nullable: true description: >- Barcode string for boleto or voucher, when applicable. type: string digitable_line: nullable: true description: >- Digitable line representation of the boleto or voucher. type: string url: nullable: true description: >- URL where the boleto or voucher can be viewed or downloaded. type: string expiration_date: nullable: true description: Expiration date of the boleto or voucher. type: string format: date-time instructions: nullable: true description: >- Additional payment instructions for the boleto or voucher. type: string receipt_url: nullable: true description: URL to access the payment receipt, when available. type: string required: - barcode - digitable_line - url - expiration_date - instructions - receipt_url additionalProperties: false currency: type: string enum: - ARS - BOB - BRL - CLP - COP - CRC - GTQ - MXN - PYG - PEN - USD - UYU description: Currency of the transaction. default: BRL buyer: type: object properties: id: type: string description: Unique identifier of the buyer. format: uuid name: type: string description: Full name of the buyer. email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: Email address of the buyer. phone: type: string description: Phone number of the buyer. birth_date: type: string description: Birth date of the buyer. document: type: object properties: type: type: string enum: - DNI - CUIT - CI - CE - NIT - CPF - CNPJ - RUT - RUN - CC - CDI - PP - RUC - PAS - DPI - CUI - RFC - CURP number: type: string required: - type - number additionalProperties: false description: Buyer document information. address: type: object properties: street: type: string minLength: 1 maxLength: 255 number: type: string maxLength: 255 complement: nullable: true type: string maxLength: 255 neighborhood: type: string maxLength: 255 city: type: string minLength: 1 maxLength: 255 state: type: string minLength: 2 maxLength: 3 pattern: ^[\p{L}\p{N}]{2,3}$ zipCode: type: string maxLength: 255 country: default: BR type: string enum: - AR - BO - BR - CL - CO - CR - EC - GT - MX - PA - PY - PE - UY required: - street - city - country additionalProperties: false description: Buyer billing or shipping address. required: - id - name - email - phone - birth_date - document - address additionalProperties: false description: Buyer details associated with the transaction. external_ref: nullable: true description: External reference originally provided by your system. type: string fee: type: object properties: net_amount: type: integer minimum: 0 maximum: 100000000 description: >- Net amount in cents that will be settled after fees. estimated_fee: type: integer minimum: 0 maximum: 100000000 description: >- Estimated processing fee in cents for this transaction. required: - net_amount - estimated_fee additionalProperties: false description: Fee breakdown for the transaction. installments: nullable: true description: >- Number of installments for the transaction, if applicable. type: integer minimum: 1 maximum: 18 informations: description: >- Custom key/value metadata you attached on create, echoed back. type: array items: type: object properties: key: type: string description: Key of the additional information entry. value: type: string description: Value of the additional information entry. required: - key - value additionalProperties: false paid_amount: type: integer minimum: 0 maximum: 100000000 description: Total amount in cents that has been paid. paid_at: nullable: true description: >- Timestamp of when the transaction was paid, if applicable. type: string format: date-time method: type: string enum: - pix - voucher - credit_card description: Payment method actually used in the transaction. default: pix pix: nullable: true description: PIX payment details when the method is PIX. type: object properties: qr_code: type: string description: PIX QR code payload for payment. expiration_date: description: PIX QR code expiration date. type: string format: date-time end_to_end_id: nullable: true description: >- End-to-end identifier assigned to the PIX payment, when available. type: string receipt_url: nullable: true description: >- URL to access the PIX payment receipt, when available. type: string required: - qr_code - expiration_date - end_to_end_id - receipt_url additionalProperties: false refunded_amount: type: integer minimum: 0 maximum: 100000000 description: Total refunded amount in cents for this transaction. products: type: array items: type: object properties: name: type: string maxLength: 255 description: Product name or title. price: type: integer minimum: 0 maximum: 100000000 description: Unit price in cents for the product. quantity: type: integer minimum: 1 maximum: 999999 description: Quantity of this product. required: - name - price - quantity additionalProperties: false description: List of products included in the transaction. metadata: nullable: true description: >- Arbitrary key-value metadata associated with the transaction. type: object additionalProperties: type: string traceable: type: boolean description: Indicates whether the transaction is traceable. ip_address: nullable: true description: IPv4 or IPv6 address associated with the transaction. anyOf: - type: string format: ipv4 pattern: >- ^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$ - type: string format: ipv6 pattern: >- ^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$ status: type: string enum: - authorized - canceled - captured - chargedback - three_ds_required - expired - in_protest - paid - paid_externally - partially_paid - partially_refunded - pending - processing - processed - refunded - med - pre_chargedback - refused description: Current external status of the transaction. next_action: nullable: true description: >- Next action required to complete the transaction, such as 3DS authentication. type: object properties: type: type: string enum: - three_ds_challenge description: The type of next action required. challenge_session_id: type: string description: Challenge session identifier for 3DS resolution. client_secret: type: string description: Client secret for SDK polling authentication. expires_at: description: Expiration timestamp for the challenge session. type: string format: date-time three_ds_stage: description: >- Whether the challenge runs before or after the charge. Absent means post_charge. type: string enum: - pre_charge - post_charge required: - type - challenge_session_id - client_secret - expires_at additionalProperties: false attribution: nullable: true description: >- Marketing attribution captured at checkout. Null for transactions created directly through the API. type: object properties: utm_source: description: >- Traffic source that brought the buyer, from `utm_source`. nullable: true type: string utm_medium: description: Marketing medium, from `utm_medium`. nullable: true type: string utm_campaign: description: Campaign name, from `utm_campaign`. nullable: true type: string utm_content: description: Creative or ad variation, from `utm_content`. nullable: true type: string utm_term: description: Paid keyword or term, from `utm_term`. nullable: true type: string fbc: description: Meta click identifier captured at checkout. nullable: true type: string fbp: description: Meta browser identifier captured at checkout. nullable: true type: string gclid: description: Google Ads click identifier captured at checkout. nullable: true type: string ttclid: description: TikTok Ads click identifier captured at checkout. nullable: true type: string src: description: Generic source parameter captured at checkout. nullable: true type: string sck: description: Generic sub-source parameter captured at checkout. nullable: true type: string checkout_url: description: Full checkout URL the buyer landed on. nullable: true type: string referrer_url: description: Page the buyer came from before the checkout. nullable: true type: string additionalProperties: false created_at: description: Date and time when the transaction was created. type: string format: date-time updated_at: description: Date and time when the transaction was last updated. type: string format: date-time required: - id - amount - currency - buyer - fee - paid_amount - method - refunded_amount - products - traceable - status - created_at - updated_at additionalProperties: false required: - success - requestId - data additionalProperties: false example: success: true requestId: 0190a2b4-18a7-7de0-9a43-69b7cf261201 data: id: 018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f amount: 100 currency: ARS buyer: id: 018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f name: string email: developer@example.com phone: string birth_date: string document: type: DNI number: string address: street: string city: string country: AR fee: net_amount: 0 estimated_fee: 0 paid_amount: 0 method: pix refunded_amount: 0 products: - name: string price: 0 quantity: 1 traceable: false status: authorized created_at: '2026-07-14T12:00:00.000Z' updated_at: '2026-07-14T12:00:00.000Z' '400': description: HTTP 400 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '401': description: HTTP 401 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '404': description: HTTP 404 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '422': description: HTTP 422 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} application/problem+json: schema: $ref: '#/components/schemas/ValidationProblemDetails' '429': description: HTTP 429 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} default: description: RFC 7807 Problem Details error response content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] components: schemas: ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string code: type: string additionalProperties: true additionalProperties: true ProblemDetails: type: object description: RFC 7807 Problem Details object. properties: type: type: string format: uri-reference title: type: string status: type: number detail: type: string instance: type: string format: uri-reference required: - type - title - status - detail additionalProperties: true securitySchemes: BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: apiKey BasicAuth: type: http scheme: basic description: Use Basic auth with username `token` and password `x`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.