logo
API docs by Redocly

Sulpayments API documentation (1.0.0)

Download OpenAPI specification:Download

Authentication

These APIs use Mutual TLS as authentication method.

This method requires both the client and the server to confirm their identity with a certificate. Once the identity of both parties is confirmed, an encrypted connection is established.

Ask for a certificate in order to access the functionalities of the api.

If you are using postman here is an example on how to work with certificates in Postman

Find below an example on how to make a request using the certificate given.

// typescript
import axios from "axios";
import https from "https";
import fs from "fs";

const serverURL = "https://my.server";
const pfxPath = "/path/to/client.pfx"; // Replace with the path to your PFX file

const agent = new https.Agent({
  pfx: fs.readFileSync(pfxPath),
  passphrase: "your_pfx_file_password", // Replace with the password for your PFX file, if applicable
});
const requestData = {
  // Your request payload here
};
axios
  .post(serverURL, requestData, { httpsAgent: agent })
  .then((response) => {
    console.log("Response:", response.data);
  })
  .catch((error) => {
    console.error("Request error:", error.message);
  });

Payment Process Using Credit Card

To complete the payment using a credit card, the following flow must be followed (see the illustrative diagrams below for better understanding):

credit card payment flow successful flow

In the first scenario:

  1. The first request is sent to the endpoint /order/v1/client-token-3ds/card-token with the necessary data for token generation (refer to the documentation below for request details).
  2. With the token generated using the card and user data, the second request is made to the endpoint /order/v3/transparent to finalize the order, populating the specialPaymentDetails.card3DSToken field with the token generated in step 1.
  3. The payment is either PAID or CANCELED synchronously, and the response is returned to the client.

credit card payment with challenge flow

In the second scenario:

  1. The first request is sent to the endpoint /order/v1/client-token-3ds/card-token with the necessary data for token generation (refer to the documentation below for request details).
  2. With the token generated using the card and user data, the second request is made to the endpoint /order/v3/transparent to finalize the order, populating the specialPaymentDetails.card3DSToken field with the token generated in step 1.
  3. If the payment status returned in step 2 is ANALYSIS, a challenge URL (field challengeUrl) is included in the response payload to the client. The user must be redirected to this URL to complete the challenge process on his bank.
  4. After the user completes the challenge, the payment is confirmed via webhook notification to the client.

Authentication Token

Token

Azure Entra application authentication token.

Request Body schema: application/json
required
clientSecret
required
string

Client secret.

clientId
required
string

Client Id of the application.

scopes
required
Array of strings

List of scopes.

Responses

Request samples

Content type
application/json
{
  • "clientSecret": "p-TlX2dEFBAE3XpUVXI30bF5nSXHKP",
  • "clientId": "ae191cfb-1d2f-4356-81e3-ca5e27c357eb",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "tokenType": "string",
  • "expiresIn": 0,
  • "token": "string"
}

Postback

Your postback notification for an order.

Every time a transaction has its status changed, your system will receive a notification from ours, so that you know if transactions were paid.

We expect that your system returns to ours: status code 200. If not, we'll retry 6 more times.

Request Body schema: application/json
required
id
required
string

The id of the order of which to retrieve the details.

code
required
string

Order id in your system.

status
required
string
Enum: "PENDING" "PAID" "EXPIRED" "REFUNDED" "CANCELED" "ERROR"

Order status.

paidAt
required
string

The date the order was paid.

updatedAt
required
string

The date the order was updated.

type
required
string
Enum: "PAY-IN" "PAY-OUT" "REFUND"

The webhook order type.

message
string

The message.

required
object

Amount of the order

object or null

The owner bank. Returns data only when payment method is PIX

object or null

The payer bank data.

Responses

Request samples

Content type
application/json
{
  • "id": "de05f0db-e6a3-462e-8f1c-8dc8dd07c278",
  • "code": "2345678726",
  • "status": "PAID",
  • "paidAt": "2022-12-17T11:35:51.923Z",
  • "updatedAt": "2022-12-17T11:35:51.923Z",
  • "type": "PAY-IN",
  • "message": "Order paid",
  • "amount": {
    },
  • "ownerBank": {
    },
  • "payer": {
    }
}

Response samples

Content type
application/json
{
  • "returnCode": "SUCCESS"
}

Your postback notification for a checkout order.

Every time a transaction has its status changed, your system will receive a notification from ours, so that you know if transactions were paid.

We expect that your system returns to ours: status code 200. If not, we'll retry 6 more times.

Request Body schema: application/json
required
id
required
string

The id of the checkout order of which to retrieve the details.

code
required
string

Order id in your system.

status
required
string
Enum: "PENDING" "PAID" "EXPIRED" "REFUNDED" "CANCELED" "ERROR"

Order status.

paidAt
required
string

The date the order was paid.

updatedAt
required
string

The date the order was updated.

type
required
string
Enum: "PAY-IN" "PAY-OUT" "REFUND"

The webhook order type.

message
string

The message.

required
object

Amount of the order

object or null

The owner bank. Returns data only when payment method is PIX

object or null

The payer bank data.

orderId
required
string

The id of the order of which to retrieve the details.

Responses

Request samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "code": "2345678726",
  • "status": "PAID",
  • "paidAt": "2022-12-17T11:35:51.923Z",
  • "updatedAt": "2022-12-17T11:35:51.923Z",
  • "type": "PAY-IN",
  • "message": "Order paid",
  • "amount": {
    },
  • "ownerBank": {
    },
  • "payer": {
    },
  • "orderId": "de05f0db-e6a3-462e-8f1c-8dc8dd07c278"
}

Response samples

Content type
application/json
{
  • "returnCode": "SUCCESS"
}

Banking - Postback

Your postback notification for a banking payin.

Every time a transaction has its status changed, your system will receive a notification from ours, so that you know if transactions were paid.

We expect that your system returns to ours: status code 200. If not, we'll retry 6 more times.

Request Body schema: application/json
required
id
required
string

Internal order identifier.

code
required
string

External order code informed at creation time.

event
required
string
Enum: "ORDER-PAYIN.PAID" "ORDER-PAYIN.EXPIRED" "ORDER-PAYIN.CANCELED" "ORDER-PAYIN.ERROR"

Webhook event for BANKING PAYIN.

status
required
string
Enum: "PAID" "EXPIRED" "CANCELED" "ERROR"

Current order status for BANKING PAYIN.

paidAt
string or null

Date when order was paid (UTC ISO-8601).

updatedAt
required
string

Date of the status transition (UTC ISO-8601).

endToEndId
string or null

PIX endToEndId when provided by the financial partner.

type
required
string
Value: "PAY-IN"

Webhook type.

message
required
string

Human-readable status message.

required
object

Order amount.

object

Destination account (owner) information when available.

required
object

Payer information.

Responses

Request samples

Content type
application/json
{
  • "id": "de05f0db-e6a3-462e-8f1c-8dc8dd07c278",
  • "code": "payin-12345",
  • "event": "ORDER-PAYIN.PAID",
  • "status": "PAID",
  • "paidAt": "2026-02-19T13:32:21.552Z",
  • "updatedAt": "2026-02-19T13:32:21.552Z",
  • "endToEndId": "E12345678202602191332a1b2c3d4e5f",
  • "type": "PAY-IN",
  • "message": "Order paid",
  • "amount": {
    },
  • "ownerBank": {
    },
  • "payer": {
    }
}

Response samples

Content type
application/json
{
  • "returnCode": "SUCCESS"
}

Your postback notification for a banking payout.

Every time a transaction has its status changed, your system will receive a notification from ours, so that you know if transactions were paid.

We expect that your system returns to ours: status code 200. If not, we'll retry 6 more times.

Request Body schema: application/json
required
id
required
string

Internal order identifier.

code
required
string

External order code informed at creation time.

event
required
string
Enum: "ORDER-PAYOUT.PAID" "ORDER-PAYOUT.CANCELED" "ORDER-PAYOUT.ERROR"

Webhook event for BANKING PAYOUT.

status
required
string
Enum: "PAID" "CANCELED" "ERROR"

Current order status for BANKING PAYOUT.

paidAt
string or null

Date when order was paid (UTC ISO-8601).

updatedAt
required
string

Date of the status transition (UTC ISO-8601).

endToEndId
string or null

PIX endToEndId when provided by the financial partner.

type
required
string
Value: "PAY-OUT"

Webhook type.

message
required
string

Human-readable status message.

required
object

Order amount.

object

Origin account (owner) information when available.

required
object

Receiver information.

Responses

Request samples

Content type
application/json
{
  • "id": "8ba1d4ff-2bc2-45c7-8e60-ec57ab9931de",
  • "code": "payout-12345",
  • "event": "ORDER-PAYOUT.PAID",
  • "status": "PAID",
  • "paidAt": "2026-02-19T13:34:18.177Z",
  • "updatedAt": "2026-02-19T13:34:18.177Z",
  • "endToEndId": "E12345678202602191334z9y8x7w6v5u",
  • "type": "PAY-OUT",
  • "message": "Order paid",
  • "amount": {
    },
  • "ownerBank": {
    },
  • "receiver": {
    }
}

Response samples

Content type
application/json
{
  • "returnCode": "SUCCESS"
}

Your postback notification for approved banking account requests.

Every time a transaction has its status changed, your system will receive a notification from ours, so that you know if transactions were paid.

We expect that your system returns to ours: status code 200. If not, we'll retry 6 more times.

Request Body schema: application/json
required
accountId
required
string

Account identifier created after request approval.

event
required
string
Value: "ACCOUNT.CREATED"

Webhook event for approved account request.

occurredAt
required
string

When the event occurred (UTC ISO-8601).

requestId
required
string

Identifier of the original account creation request.

status
required
string
Enum: "ACTIVE" "INACTIVE" "CLOSED"

Current account status.

object

Bank account data returned when the account is created with bank data.

createdAt
required
string

Account creation date (UTC ISO-8601).

updatedAt
required
string

Account update date (UTC ISO-8601).

Responses

Request samples

Content type
application/json
{
  • "accountId": "63ec5f2e-688f-4cf4-a24b-1a4ac0474b0e",
  • "event": "ACCOUNT.CREATED",
  • "occurredAt": "2026-02-19T13:40:05.020Z",
  • "requestId": "045a2fb2-0b11-4f8c-8ab6-8b61db66d189",
  • "status": "ACTIVE",
  • "bankData": {
    },
  • "createdAt": "2026-02-19T13:40:05.020Z",
  • "updatedAt": "2026-02-19T13:40:05.020Z"
}

Response samples

Content type
application/json
{
  • "returnCode": "SUCCESS"
}

Your postback notification for rejected banking account requests.

Every time a transaction has its status changed, your system will receive a notification from ours, so that you know if transactions were paid.

We expect that your system returns to ours: status code 200. If not, we'll retry 6 more times.

Request Body schema: application/json
required
event
required
string
Value: "ACCOUNT.REJECTED"

Webhook event for rejected account request.

occurredAt
required
string

When the event occurred (UTC ISO-8601).

requestId
required
string

Identifier of the rejected account creation request.

status
required
string
Value: "REJECTED"

Status for account request rejection webhook.

required
object

Reason for account request rejection.

Responses

Request samples

Content type
application/json
{
  • "event": "ACCOUNT.REJECTED",
  • "occurredAt": "2026-02-19T13:41:12.991Z",
  • "requestId": "045a2fb2-0b11-4f8c-8ab6-8b61db66d189",
  • "status": "REJECTED",
  • "reason": {
    }
}

Response samples

Content type
application/json
{
  • "returnCode": "SUCCESS"
}

Order

Get a list of your orders

Get a list of your orders based the data entered as a filter.

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
query Parameters
id
string

Unique identifier of the order.

idempotencyKey
string

IdempotencyKey to filter.

code
string

Order code.

customerEmail
string

Customer email.

customerName
string

Customer name

customerDocumentNumber
string

Customer document number

status
string
Enum: "INITIAL" "PENDING" "PAID" "EXPIRED" "ANALYSIS" "REFUNDED" "PARTIAL_REFUNDED" "CANCELED" "ERROR"
Example: status=PAID

Order status.

paymentMethod
string
Enum: "PIX" "DEPOSIT" "BOLETO" "BINANCE_PAY" "CREDIT_CARD" "CASH" "SPEI" "OXXO" "PAYNET"
Example: paymentMethod=BINANCE_PAY

Payment method.

startDate
required
string
Example: startDate=2022-18-12

The search start date, in the following format YYYY-MM-DD. It is required if no id, code, or idempotency key is provided.

endDate
required
string
Example: endDate=2022-18-12

The search end date, in the following format YYYY-MM-DD. It is required if no id, code, or idempotency key is provided

sortBy
required
string
Enum: "createdAt" "paidAt" "refundedAt"
Example: sortBy=createdAt

Field to be used as sort.

direction
required
string
Enum: "ASC" "DESC"
Example: direction=DESC

Direction of the sort.

page
required
string
Example: page=1

The page to return.

perPage
required
string
Example: perPage=20

The record count per page.

Responses

Response samples

Content type
application/json
{}

Check transaction status

You can check the transaction status at any time.

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{}

Create Transparent Order - V1 Deprecated

The transaction is called transparent as it has no interface and/or screen that your customer should interact with.

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The customer of the order.

required
object

The order details.

required
object

The merchant of the order.

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "order": {
    },
  • "merchant": {
    }
}

Response samples

Content type
application/json
{}

Refund an order - V1 Deprecated

Refund an order by the way only order with payment methods BINANCE_PAY, PIX and SPEI are allowed to refund. For other payment methods, we are implementing them.

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
orderId
required
string

Order id

reason
required
string [ 5 .. 100 ] characters

Reason for Refund.

For orders of Mexico the reason must be one of the follwoing values bellow:

  • DUPLICATE
  • FRAUDULENT
  • REQUESTED_BY_CUSTOMER
  • OTHER
required
object

Who requested the refund

Responses

Request samples

Content type
application/json
{
  • "orderId": "f40f2dcd-4818-4629-a7e7-41afa8ecec00",
  • "reason": "Customer requested or order was not delivered",
  • "requestedBy": {}
}

Response samples

Content type
application/json
{
  • "id": "952cb9f7-562b-4e28-83ee-35501c9246fe",
  • "orderId": "b9e4eb1e-971f-4b19-abf0-3dd6a2cf41fd",
  • "amount": 100,
  • "reason": "Customer requested or order was not delivered",
  • "requestedBy": "[email protected]",
  • "status": "INITIAL",
  • "createdAt": "2021-01-01T00:00:00.000Z",
  • "endToEndId": "string"
}

Get refund by id

Returns a refund information

Authorizations:
Bearer
path Parameters
refundId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "952cb9f7-562b-4e28-83ee-35501c9246fe",
  • "orderId": "b9e4eb1e-971f-4b19-abf0-3dd6a2cf41fd",
  • "amount": 100,
  • "reason": "Customer requested or order was not delivered",
  • "requestedBy": "[email protected]",
  • "status": "INITIAL",
  • "createdAt": "2021-01-01T00:00:00.000Z",
  • "endToEndId": "string"
}

Get refunds by filter

Returns the information of all refunds according to the filter

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
query Parameters
id
string
Example: id=1ef64feb-4697-4458-990f-58c338b45588

The id of the refund

idempotencyKey
string
Example: idempotencyKey=1ef64feb-4697-4458-990f-58c338b45588

The idempotency key of the refund

status
string
Enum: "INITIAL" "PROCESSING" "SUCCESS" "ERROR" "REJECTED"
Example: status=SUCCESS

The status of the refund

orderId
string
Example: orderId=1ef64feb-4697-4458-990f-58c338b45588

The id of the order

startDate
required
string
Example: startDate=2022-18-12

The search start date, in the following format YYYY-MM-DD. It is required if no id, order id, or idempotency key is provided.

endDate
required
string
Example: endDate=2022-18-12

The search end date, in the following format YYYY-MM-DD. It is required if no id, order id, or idempotency key is provided

page
required
string
Example: page=1

The page to return.

perPage
required
string
Example: perPage=20

The record count per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Transparent Order - V2 Deprecated

The transaction is called transparent as it has no interface and/or screen that your customer should interact with.

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The customer of the order.

required
object

The order details.

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "order": {
    }
}

Response samples

Content type
application/json
{}

Refund an order - V2

Refund an order

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
orderId
required
string

Order id

reason
required
string [ 5 .. 100 ] characters

Reason for Refund.

For orders of Mexico the reason must be one of the follwoing values bellow:

  • DUPLICATE
  • FRAUDULENT
  • REQUESTED_BY_CUSTOMER
  • OTHER
required
object

Who requested the refund

amount
required
string

Amount

Responses

Request samples

Content type
application/json
{
  • "orderId": "f40f2dcd-4818-4629-a7e7-41afa8ecec00",
  • "reason": "Customer requested or order was not delivered",
  • "requestedBy": {},
  • "amount": "10.40"
}

Response samples

Content type
application/json
{
  • "id": "952cb9f7-562b-4e28-83ee-35501c9246fe",
  • "orderId": "b9e4eb1e-971f-4b19-abf0-3dd6a2cf41fd",
  • "amount": 100,
  • "reason": "Customer requested or order was not delivered",
  • "requestedBy": "[email protected]",
  • "status": "INITIAL",
  • "createdAt": "2021-01-01T00:00:00.000Z",
  • "endToEndId": "string"
}

Create Transparent Order - V3

The transaction is called transparent as it has no interface and/or screen that your customer should interact with. This version all order will be validated by AML process, to prevent frauds.

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The customer of the order.

required
object

The order details.

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "order": {
    }
}

Response samples

Content type
application/json
{}

Payout

Brazil payout - V1 Deprecated 

  Request a payout for Brazil country

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The payout amount

paymentMethod
string
Enum: "PIX" "TED" "TETHER"

Payment Method

required
object

The payout customer

required
object

The payout bank information

OBS: If you send this pix data, you don't need to send the account data or vice-versa

object

Crypto

description
required
string

The payout description.

webhookUrl
required
string

The webhook url to receive the payout status

code
required
string

Order id in your system.

Responses

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "paymentMethod": "PIX",
  • "customer": {
    },
  • "bank": {
    },
  • "crypto": {
    },
  • "description": "string",
  • "webhookUrl": "https://your-webhook-url.com",
  • "code": "order_id_in_your_system"
}

Response samples

Content type
application/json
{
  • "id": "386c6844-62ec-4cc1-9408-f274ca911e45",
  • "amount": "string",
  • "status": "PAID",
  • "fee": {
    },
  • "errorMessage": "string",
  • "createdAt": "2026-02-20T14:33:57.762Z"
}

Get Brazil payout data by id

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "2e6bc571-082d-46ba-8b89-6fbb17fe0ee4",
  • "idempotencyKey": "4f143b92-121e-4b0d-8652-90c389cb9864",
  • "description": "Customer withdraw",
  • "amount": "100.00",
  • "status": "PAID",
  • "errorMessage": "An unexpected error occurred",
  • "createdAt": "2026-02-20T14:34:05.243Z",
  • "crypto": {
    },
  • "paymentMethod": "PIX",
  • "bank": {
    },
  • "customer": {
    },
  • "owner": {
    },
  • "endToEndId": "428263ec-eb00-44f6-a031-e19ed3ac9dab",
  • "receiver": {
    },
  • "fee": {
    }
}

Get Brazil payout data by idepotency key

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
path Parameters
idempotencyKey
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "2e6bc571-082d-46ba-8b89-6fbb17fe0ee4",
  • "idempotencyKey": "4f143b92-121e-4b0d-8652-90c389cb9864",
  • "description": "Customer withdraw",
  • "amount": "100.00",
  • "status": "PAID",
  • "errorMessage": "An unexpected error occurred",
  • "createdAt": "2026-02-20T14:34:05.243Z",
  • "crypto": {
    },
  • "paymentMethod": "PIX",
  • "bank": {
    },
  • "customer": {
    },
  • "owner": {
    },
  • "endToEndId": "428263ec-eb00-44f6-a031-e19ed3ac9dab",
  • "receiver": {
    },
  • "fee": {
    }
}

Mexico payout - V1 

  Request a payout for Mexico country

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The payout amount

required
object

The payout customer

paymentMethod
string
Enum: "SPEI" "KIOSKO" "TETHER"

Payment Method

required
object

The payout bank information

object

Crypto

description
required
string

The payout description.

webhookUrl
required
string

The webhook url to receive the payout status

code
required
string

Order id in your system.

Responses

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "customer": {
    },
  • "paymentMethod": "SPEI",
  • "bank": {
    },
  • "crypto": {
    },
  • "description": "string",
  • "webhookUrl": "https://your-webhook-url.com",
  • "code": "order_id_in_your_system"
}

Response samples

Content type
application/json
{
  • "id": "386c6844-62ec-4cc1-9408-f274ca911e45",
  • "amount": "string",
  • "status": "PAID",
  • "fee": {
    },
  • "errorMessage": "string",
  • "createdAt": "2026-02-20T14:33:57.762Z"
}

Get Mexico payout data by id

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "2e6bc571-082d-46ba-8b89-6fbb17fe0ee4",
  • "idempotencyKey": "4f143b92-121e-4b0d-8652-90c389cb9864",
  • "description": "Customer withdraw",
  • "amount": "100.00",
  • "status": "PAID",
  • "errorMessage": "An unexpected error occurred",
  • "createdAt": "2026-02-20T14:34:05.243Z",
  • "crypto": {
    },
  • "financialPartner": "GAMECASH",
  • "paymentMethod": "SPEI",
  • "customer": {
    },
  • "bank": {
    }
}

Brazil payout - V2 

  Request a payout for Brazil country

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The payout amount

paymentMethod
string
Enum: "PIX" "TED" "TETHER"

Payment Method

required
object

The payout customer

required
object

The payout bank information

OBS: If you send this pix data, you don't need to send the account data or vice-versa

object

Crypto

description
required
string

The payout description.

webhookUrl
required
string

The webhook url to receive the payout status

Responses

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "paymentMethod": "PIX",
  • "customer": {
    },
  • "bank": {
    },
  • "crypto": {
    },
  • "description": "string",
  • "webhookUrl": "https://your-webhook-url.com"
}

Response samples

Content type
application/json
{
  • "id": "386c6844-62ec-4cc1-9408-f274ca911e45",
  • "amount": "string",
  • "status": "PAID",
  • "fee": {
    },
  • "errorMessage": "string",
  • "createdAt": "2026-02-20T14:33:57.762Z"
}

Brazil payout - V3 

  Request a payout for Brazil country

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The payout amount

paymentMethod
string
Enum: "PIX" "TED" "TETHER"

Payment Method

required
object

The payout customer

required
object

The payout bank information

OBS: If you send this pix data, you don't need to send the account data or vice-versa

object

Crypto

description
required
string

The payout description.

webhookUrl
required
string

The webhook url to receive the payout status

code
required
string

Order id in your system.

Responses

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "paymentMethod": "PIX",
  • "customer": {
    },
  • "bank": {
    },
  • "crypto": {
    },
  • "description": "string",
  • "webhookUrl": "https://your-webhook-url.com",
  • "code": "order_id_in_your_system"
}

Response samples

Content type
application/json
{
  • "id": "386c6844-62ec-4cc1-9408-f274ca911e45",
  • "amount": "string",
  • "status": "PAID",
  • "fee": {
    },
  • "errorMessage": "string",
  • "createdAt": "2026-02-20T14:33:57.762Z"
}

Client Token 3DS

Get 3DS client token Deprecated

Get 3DS client token by provider

path Parameters
provider
required
string
Value: "REDPAY"
Example: REDPAY

The provider name, that you want to get the client token.

Responses

Response samples

Content type
application/json
{
  • "clientToken": "string"
}

Generate card token

Generate card token by Provider

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Request Body schema: application/json
required
object

The card data.

object

The billing address.

required
object

Amount of the transaction.

required
object

The document of the customer.

Responses

Request samples

Content type
application/json
{
  • "card": {
    },
  • "address": {
    },
  • "amount": {
    },
  • "document": {
    }
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Checkout

Create Checkout - V1 Deprecated

Create a Checkout link for payment

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The customer of the checkout.

required
object

The checkout details.

country
required
string
Enum: "AFG" "ALB" "DZA" "ASM" "AND" "AGO" "AIA" "ATA" "ATG" "ARG" "ARM" "ABW" "AUS" "AUT" "AZE" "BHS" "BHR" "BGD" "BRB" "BLR" "BEL" "BLZ" "BEN" "BMU" "BTN" "BOL" "BES" "BIH" "BWA" "BVT" "BRA" "IOT" "BRN" "BGR" "BFA" "BDI" "CPV" "KHM" "CMR" "CAN" "CYM" "CAF" "TCD" "CHL" "CHN" "CXR" "CCK" "COL" "COM" "COG" "COD" "COK" "CRI" "HRV" "CUB" "CUW" "CYP" "CZE" "DNK" "DJI" "DMA" "DOM" "ECU" "EGY" "SLV" "GNQ" "ERI" "EST" "ETH" "FLK" "FRO" "FJI" "FIN" "FRA" "GUF" "PYF" "ATF" "GAB" "GMB" "GEO" "DEU" "GHA" "GIB" "GRC" "GRL" "GRD" "GLP" "GUM" "GTM" "GGY" "GIN" "GNB" "GUY" "HTI" "HMD" "VAT" "HND" "HKG" "HUN" "ISL" "IND" "IDN" "IRN" "IRQ" "IRL" "IMN" "ISR" "ITA" "JAM" "JPN" "JEY" "JOR" "KAZ" "KEN" "KIR" "PRK" "KOR" "KWT" "KGZ" "LAO" "LVA" "LBN" "LSO" "LBR" "LBY" "LIE" "LTU" "LUX" "MAC" "MDG" "MWI" "MYS" "MDV" "MLI" "MLT" "MHL" "MTQ" "MRT" "MUS" "MYT" "MEX" "FSM" "MDA" "MCO" "MNG" "MNE" "MSR" "MAR" "MOZ" "MMR" "NAM" "NRU" "NPL" "NLD" "NCL" "NZL" "NIC" "NER" "NGA" "NIU" "NFK" "MNP" "NOR" "OMN" "PAK" "PLW" "PSE" "PAN" "PNG" "PRY" "PER" "PHL" "PCN" "POL" "PRT" "PRI" "QAT" "REU" "ROU" "RUS" "RWA" "BLM" "SHN" "KNA" "LCA" "MAF" "SPM" "VCT" "WSM" "SMR" "STP" "SAU" "SEN" "SRB" "SYC" "SLE" "SGP" "SXM" "SVK" "SVN" "SLB" "SOM" "ZAF" "SGS" "SSD" "ESP" "LKA" "SDN" "SUR" "SJM" "SWE" "CHE" "SYR" "TWN" "TJK" "TZA" "THA" "TLS" "TGO" "TKL" "TON" "TTO" "TUN" "TUR" "TKM" "TCA" "TUV" "UGA" "UKR" "ARE" "GBR" "USA" "UMI" "URY" "UZB" "VUT" "VEN" "VNM" "VGB" "VIR" "WLF" "ESH" "YEM" "ZMB" "ZWE"

The country of the Merchant

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "order": {},
  • "country": "BRA"
}

Response samples

Content type
application/json
{}

Get Checkout by id

Get checkout data by id

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
path Parameters
checkoutId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "customer": {
    },
  • "status": "string",
  • "description": "string",
  • "code": "string",
  • "paymentMethod": "string",
  • "amount": {
    },
  • "country": "string",
  • "redirectUrl": "string",
  • "webhookUrl": "string",
  • "universalLink": "string",
  • "errorMessage": "string"
}

Create Checkout - V2

Create a Checkout link for payment

This version all checkout orders will be validated by AML process, to prevent frauds.

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer
header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
required
object

The customer of the checkout.

required
object

The checkout details.

country
required
string
Enum: "AFG" "ALB" "DZA" "ASM" "AND" "AGO" "AIA" "ATA" "ATG" "ARG" "ARM" "ABW" "AUS" "AUT" "AZE" "BHS" "BHR" "BGD" "BRB" "BLR" "BEL" "BLZ" "BEN" "BMU" "BTN" "BOL" "BES" "BIH" "BWA" "BVT" "BRA" "IOT" "BRN" "BGR" "BFA" "BDI" "CPV" "KHM" "CMR" "CAN" "CYM" "CAF" "TCD" "CHL" "CHN" "CXR" "CCK" "COL" "COM" "COG" "COD" "COK" "CRI" "HRV" "CUB" "CUW" "CYP" "CZE" "DNK" "DJI" "DMA" "DOM" "ECU" "EGY" "SLV" "GNQ" "ERI" "EST" "ETH" "FLK" "FRO" "FJI" "FIN" "FRA" "GUF" "PYF" "ATF" "GAB" "GMB" "GEO" "DEU" "GHA" "GIB" "GRC" "GRL" "GRD" "GLP" "GUM" "GTM" "GGY" "GIN" "GNB" "GUY" "HTI" "HMD" "VAT" "HND" "HKG" "HUN" "ISL" "IND" "IDN" "IRN" "IRQ" "IRL" "IMN" "ISR" "ITA" "JAM" "JPN" "JEY" "JOR" "KAZ" "KEN" "KIR" "PRK" "KOR" "KWT" "KGZ" "LAO" "LVA" "LBN" "LSO" "LBR" "LBY" "LIE" "LTU" "LUX" "MAC" "MDG" "MWI" "MYS" "MDV" "MLI" "MLT" "MHL" "MTQ" "MRT" "MUS" "MYT" "MEX" "FSM" "MDA" "MCO" "MNG" "MNE" "MSR" "MAR" "MOZ" "MMR" "NAM" "NRU" "NPL" "NLD" "NCL" "NZL" "NIC" "NER" "NGA" "NIU" "NFK" "MNP" "NOR" "OMN" "PAK" "PLW" "PSE" "PAN" "PNG" "PRY" "PER" "PHL" "PCN" "POL" "PRT" "PRI" "QAT" "REU" "ROU" "RUS" "RWA" "BLM" "SHN" "KNA" "LCA" "MAF" "SPM" "VCT" "WSM" "SMR" "STP" "SAU" "SEN" "SRB" "SYC" "SLE" "SGP" "SXM" "SVK" "SVN" "SLB" "SOM" "ZAF" "SGS" "SSD" "ESP" "LKA" "SDN" "SUR" "SJM" "SWE" "CHE" "SYR" "TWN" "TJK" "TZA" "THA" "TLS" "TGO" "TKL" "TON" "TTO" "TUN" "TUR" "TKM" "TCA" "TUV" "UGA" "UKR" "ARE" "GBR" "USA" "UMI" "URY" "UZB" "VUT" "VEN" "VNM" "VGB" "VIR" "WLF" "ESH" "YEM" "ZMB" "ZWE"

The country of the Merchant

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "order": {},
  • "country": "BRA"
}

Response samples

Content type
application/json
{}

Banks

Get available banks for DEPOSIT payment method

Returns a list of available banks that support DEPOSIT payment method.

Usage:

  1. Call this endpoint to get available banks and their slugs
  2. Use the 'slug' field from the response as the optional 'bankSlug' parameter when creating DEPOSIT orders
  3. If 'bankSlug' is not provided in order creation, system will use automatic bank selection

NOTE: Please, to authenticate use the scope: "api://app-order-prd"

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "banks": [
    ]
}

Banking - Accounts

Create account request

Create a banking account request with holder information and representatives.

Authorizations:
Bearer
header Parameters
idempotency-key
required
string

Unique key for idempotent requests

Request Body schema: application/json
required
country
required
string
Value: "BRA"

Holder country code in ISO-3

holderType
required
string
Enum: "INDIVIDUAL" "ORGANIZATION"

Holder type

fullName
required
string

Holder full name or business name.

email
required
string

Primary email of the holder.

phone
required
string

Primary phone of the holder.

birthdate
required
string

Holder birthdate or foundation date (YYYY-MM-DD).

required
object

Holder identification document.

required
object

Complete holder address.

Array of objects

Representatives linked to the holder (required when holderType is ORGANIZATION).

Responses

Request samples

Content type
application/json
{
  • "country": "BRA",
  • "holderType": "ORGANIZATION",
  • "fullName": "Company LTDA",
  • "email": "[email protected]",
  • "phone": "+5511912349865",
  • "birthdate": "1990-01-01",
  • "document": {
    },
  • "address": {
    },
  • "representatives": [
    ]
}

Response samples

Content type
application/json
{
  • "accountRequestId": "d3f46d1e-3f35-4cf9-9bcb-15c0b7c8f84a",
  • "status": "PENDING"
}

Get account details

Retrieve account details by accountId.

Authorizations:
Bearer
path Parameters
accountId
required
string <uuid>

Identifier of the account

Responses

Response samples

Content type
application/json
{
  • "id": "f288ae0d-47fd-4207-aee4-0a384888bd96",
  • "status": "ACTIVE",
  • "country": "BRA",
  • "holderType": "ORGANIZATION",
  • "fullName": "Company LTDA",
  • "email": "[email protected]",
  • "phone": "+5511912345678",
  • "birthdate": "1990-01-01",
  • "document": {
    },
  • "address": {
    },
  • "representatives": [
    ],
  • "bankAccountData": {
    }
}

Account statements

Retrieve the account statement for the informed period.

Authorizations:
Bearer
path Parameters
accountId
required
string <uuid>

Identifier of the account

query Parameters
startDate
required
string
Example: startDate=2025-10-01T00:00:00Z

Start date of the statement period in ISO 8601 format

endDate
required
string
Example: endDate=2025-10-31T23:59:59Z

End date of the statement period in ISO 8601 format

currency
required
string
Example: currency=BRL

Currency used for the statement (ISO 4217)

limit
string
Default: 500
Example: limit=400

Maximum number of records returned

sort
string
Default: "desc"
Enum: "asc" "desc"
Example: sort=desc

Sorting direction for the records

cursor
string
Example: cursor=2025-10-03T13:44:32.106Z

Cursor to continue pagination (use the value returned in nextCursor)

Responses

Response samples

Content type
application/json
{
  • "params": {
    },
  • "nextCursor": "2025-10-03T13:44:32.106Z",
  • "hasNext": true,
  • "data": [
    ]
}

Create PIX key

Create a PIX key for the given account.

Authorizations:
Bearer
path Parameters
accountId
required
string <uuid>

Identifier of the account

header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Body schema: application/json
required
type
required
string
Enum: "CPF" "CNPJ" "EMAIL" "PHONE" "RANDOM"

Type of PIX key to be created

key
required
string

PIX key value (required unless type is RANDOM)

Responses

Request samples

Content type
application/json
{
  • "type": "CPF",
  • "key": "122345678900"
}

Response samples

Content type
application/json
{
  • "id": "a8f2b9c4-1e6a-4c3f-9d7b-2a1e8f9c5d10",
  • "type": "CPF",
  • "key": "122345678900",
  • "createdAt": "2025-12-18T10:15:30Z",
  • "possedAt": "2025-12-18T10:15:30Z"
}

List PIX keys

Retrieve all PIX keys for the given account.

Authorizations:
Bearer
path Parameters
accountId
required
string <uuid>

Identifier of the account

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete PIX key

Delete a PIX key linked to the given account.

Authorizations:
Bearer
path Parameters
accountId
required
string <uuid>

Identifier of the account

keyId
required
string <uuid>

Identifier of the PIX key

header Parameters
idempotency-key
required
string <uuid>

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Responses

Response samples

Content type
application/json
{
  • "error": "INVALID_REQUEST",
  • "message": "string",
  • "details": [
    ]
}

Banking - Payments

Create banking payout

Create a PIX payout using accountId as payer and different initiation types (MANUAL/KEY/STATIC_QRCODE/DYNAMIC_QRCODE).

Authorizations:
Bearer
header Parameters
idempotency-key
required
string

Unique key for idempotent requests

Request Body schema: application/json
required
externalId
required
string

External identifier of the payout

accountId
required
string <uuid>

Payer account identifier

paymentMethod
required
string
Value: "PIX"

Payment method

iniciationType
required
string
Enum: "MANUAL" "KEY" "STATIC_QRCODE" "DYNAMIC_QRCODE" "PAYMENT_TRANSACTION_INITIATION_SERVICE" "PAYER_QRCODE"

Initiation type

required
object

Receiver information

required
object

Payment data

required
object

Payout amount

description
required
string

Description of the payout

Responses

Request samples

Content type
application/json
{
  • "externalId": "payout-123",
  • "accountId": "f288ae0d-47fd-4207-aee4-0a384888bd96",
  • "paymentMethod": "PIX",
  • "iniciationType": "KEY",
  • "receiver": {
    },
  • "paymentData": {},
  • "amount": {
    },
  • "description": "Invoice 123 payout"
}

Response samples

Content type
application/json
{
  • "id": "c1c4c0b1-3bb8-4b1c-9e47-3f4a6f3a1b2c",
  • "externalId": "payout-123",
  • "status": "PENDING",
  • "amount": "50.00",
  • "currency": "BRL",
  • "description": "Invoice 123",
  • "endToEndId": "E12345678920240101120000abcd"
}

Create banking payin

Generate a PIX payin QR Code for a company account.

Authorizations:
Bearer
header Parameters
idempotency-key
required
string

Unique key for idempotent requests

Request Body schema: application/json
required
externalId
required
string

External identifier of the payin

accountId
required
string <uuid>

Receiver account identifier

paymentMethod
required
string
Value: "PIX"

Payment method

pixKey
string

PIX key used to generate the QR Code

required
object

Payer information

required
object

Payin amount

description
string

Description of the payin

expiration
number

Expiration time in seconds for the QR Code

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "accountId": "f288ae0d-47fd-4207-aee4-0a384888bd96",
  • "paymentMethod": "PIX",
  • "pixKey": "[email protected]",
  • "payer": {
    },
  • "amount": {
    },
  • "description": "Order #1234",
  • "expiration": 86400
}

Response samples

Content type
application/json
{
  • "id": "c1c4c0b1-3bb8-4b1c-9e47-3f4a6f3a1b2c",
  • "externalId": "external-123",
  • "status": "PENDING",
  • "qrcodeImageBase64": "iVBORw0KGgoAAAANSUhEUg...",
  • "qrcodeData": "000201010212...",
  • "expireDateTime": "2024-01-01T12:00:00Z",
  • "amount": {
    },
  • "description": "Order #1234",
  • "conciliationId": "conciliation-123"
}

Create banking refund

Create a refund for a banking order.

Authorizations:
Bearer
header Parameters
idempotency-key
required
string

Unique key for idempotent requests

Request Body schema: application/json
required
orderId
required
string <uuid>

Order identifier to refund

externalId
string

External identifier of the refund

required
object

Refund amount

refundCode
required
string

Refund code

refundReason
string

Reason for the refund

description
string

Description of the refund

Responses

Request samples

Content type
application/json
{
  • "orderId": "f288ae0d-47fd-4207-aee4-0a384888bd96",
  • "externalId": "refund-123",
  • "amount": {
    },
  • "refundCode": "RECEIVER_REQUEST",
  • "refundReason": "Customer requested refund",
  • "description": "Partial refund for order #123"
}

Response samples

Content type
application/json
{
  • "id": "c1c4c0b1-3bb8-4b1c-9e47-3f4a6f3a1b2c",
  • "externalId": "refund-123",
  • "status": "PENDING",
  • "endToEndId": "E12345678920240101120000abcd",
  • "amount": {
    }
}

Create static PIX QR Code

Generate a static PIX QR Code for a company account.

Authorizations:
Bearer
header Parameters
idempotency-key
required
string

Unique key for idempotent requests

Request Body schema: application/json
required
accountId
required
string <uuid>

Account identifier

pixKey
required
string

PIX key used for the QR Code

required
object

Amount

description
string

Description for the QR Code

Responses

Request samples

Content type
application/json
{
  • "accountId": "f288ae0d-47fd-4207-aee4-0a384888bd96",
  • "pixKey": "[email protected]",
  • "amount": {
    },
  • "description": "Static QRCode for invoice #123"
}

Response samples

Content type
application/json
{
  • "id": "qrcode-123",
  • "qrcodeImageBase64": "iVBORw0KGgoAAAANSUhEUg...",
  • "qrcodeData": "000201010212...",
  • "amount": {
    },
  • "description": "Static QRCode for invoice #123",
  • "conciliationId": "conciliation-123"
}

Account

Get balance

Return holder accounts balance from company authenticated token.

NOTE: Please, to authenticate use the scope: "api://app-account-prd"

Authorizations:
Bearer
query Parameters
accountType
required
string
Enum: "ADMINISTRATIVE" "RESERVE" "ADMINISTRATIVE_OUT" "PAYMENT"

Represents the account type

Responses

Response samples

Content type
application/json
{
  • "id": "a5d422f5-ad41-4ca0-ad9d-4ba02e521e95",
  • "fullName": "John Doe",
  • "document": {
    },
  • "country": "BRA",
  • "createdAt": "2021-01-01T00:00:00.000Z",
  • "accounts": [
    ]
}