Mark a Transaction as Paid Externally

PUT

transactions

{id}

paid-externally

curl --request PUT \
  --url https://api.pagou.ai/v2/transactions/{id}/paid-externally \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "Pago por transferência bancária",
  "external_reference": "TED-2026-10-27-0042"
}
'

import requests

url = "https://api.pagou.ai/v2/transactions/{id}/paid-externally"

payload = {
    "reason": "Pago por transferência bancária",
    "external_reference": "TED-2026-10-27-0042"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    reason: 'Pago por transferência bancária',
    external_reference: 'TED-2026-10-27-0042'
  })
};

fetch('https://api.pagou.ai/v2/transactions/{id}/paid-externally', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pagou.ai/v2/transactions/{id}/paid-externally",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => 'Pago por transferência bancária',
    'external_reference' => 'TED-2026-10-27-0042'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pagou.ai/v2/transactions/{id}/paid-externally"

	payload := strings.NewReader("{\n  \"reason\": \"Pago por transferência bancária\",\n  \"external_reference\": \"TED-2026-10-27-0042\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.pagou.ai/v2/transactions/{id}/paid-externally")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"Pago por transferência bancária\",\n  \"external_reference\": \"TED-2026-10-27-0042\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pagou.ai/v2/transactions/{id}/paid-externally")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"Pago por transferência bancária\",\n  \"external_reference\": \"TED-2026-10-27-0042\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

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.

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

curl -X PUT "https://api.pagou.ai/v2/transactions/{id}/paid-externally" \
  -H "Authorization: Bearer <API_KEY>" \
  -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, with status: "paid_externally".

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string<uuid>

required

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)$

Body

application/json

reason

string

required

Why the sale is being marked as paid outside the platform. Required.

Required string length: 1 - 500

Example:

"Pago por transferência bancária"

external_reference

string | null

Your own reference for the outside payment, such as a bank transfer id.

Required string length: 1 - 255

Example:

"TED-2026-10-27-0042"

Response

Success

success

boolean

required

requestId

string

required

data

object

required

Show child attributes

Mark a Transaction as Paid Externally

curl --request PUT \
  --url https://api.pagou.ai/v2/transactions/{id}/paid-externally \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "Pago por transferência bancária",
  "external_reference": "TED-2026-10-27-0042"
}
'

import requests

url = "https://api.pagou.ai/v2/transactions/{id}/paid-externally"

payload = {
    "reason": "Pago por transferência bancária",
    "external_reference": "TED-2026-10-27-0042"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    reason: 'Pago por transferência bancária',
    external_reference: 'TED-2026-10-27-0042'
  })
};

fetch('https://api.pagou.ai/v2/transactions/{id}/paid-externally', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pagou.ai/v2/transactions/{id}/paid-externally",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => 'Pago por transferência bancária',
    'external_reference' => 'TED-2026-10-27-0042'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pagou.ai/v2/transactions/{id}/paid-externally"

	payload := strings.NewReader("{\n  \"reason\": \"Pago por transferência bancária\",\n  \"external_reference\": \"TED-2026-10-27-0042\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.pagou.ai/v2/transactions/{id}/paid-externally")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"Pago por transferência bancária\",\n  \"external_reference\": \"TED-2026-10-27-0042\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pagou.ai/v2/transactions/{id}/paid-externally")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"Pago por transferência bancária\",\n  \"external_reference\": \"TED-2026-10-27-0042\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

Customers

Transactions

Checkout Links

Transfers

Subscriptions

Legacy v1

Mark a Transaction as Paid Externally

Which transactions can be marked

Request fields

Idempotency

If the buyer also pays through Pagou

Errors

Example

Authorizations

Path Parameters

Body

Response

​Which transactions can be marked

​Request fields

​Idempotency

​If the buyer also pays through Pagou

​Errors

​Example

Authorizations

Path Parameters

Body

Response

Which transactions can be marked

Request fields

Idempotency

If the buyer also pays through Pagou

Errors

Example