Requests and responses

Requests

• Send every request to the base URL https://9iq81tsdy4.execute-api.sa-east-1.amazonaws.com followed by the endpoint path.
• Send request bodies as JSON with the Content-Type: application/json header. The only exception is the image upload of payment links, which uses multipart/form-data.
• Include the authentication headers in every request.

Responses

Successful requests return the HTTP status 200. Most endpoints wrap the result in an envelope with the status code and a data object:

{
  "statusCode": 200,
  "data": {
    "orderId": "1a3c5e7a-9c1e-4a5c-8e9a-1c3e5a7c0029",
    "payments": ["1a3c5e7a-9c1e-4a5c-8e9a-1c3e5a7c0029"]
  }
}

Operations that change a resource usually answer with a boolean flag inside data, such as { "deleted": true } or { "updated": true }.

A few endpoints return a different shape. Always check the Responses section of the endpoint you are calling in the API reference.

Errors use a different format, described in Errors.

Amounts

Monetary values are integers in cents, and their field names end with InCents:

In financial movements, debits are negative values, for example "valueInCents": -250.

Dates

Timestamps are ISO 8601 strings in UTC with milliseconds, for example 2025-02-17T21:13:32.241Z. A few fields hold only a date in the YYYY-MM-DD format, such as the settlement date of commissions.

Filters by period use one of four formats, depending on the endpoint.

Query parameters with brackets

Used by List order revert request and List customers:

?createdAt[startsAt]=2025-01-01T00:00:00.000Z&createdAt[endsAt]=2025-01-31T23:59:59.999Z

URL-encode the brackets when your HTTP client does not do it for you: createdAt%5BstartsAt%5D.

Body fields initialDate and endDate

Used by the filter endpoints of subscriptions, withdraw requests and movements:

{ "initialDate": "2025-01-01T00:00:00.000Z", "endDate": "2025-01-31T23:59:59.999Z" }

Query parameters initialDate and endDate

Used by List commissions, with dates in the YYYY-MM-DD format:

?initialDate=2025-01-01&endDate=2025-01-31

Body objects createdAt and updatedAt

Used by Filter products:

{ "createdAt": { "startsAt": "2025-01-01T00:00:00.000Z", "endsAt": "2025-01-31T23:59:59.999Z" } }

Identifiers

Identifiers are strings. Most of them are UUIDs, such as 1c3e5a7c-9e1a-4c5e-8a9c-1e3a5c7e0001, and some are 24-character hexadecimal identifiers. Treat every identifier as an opaque string and do not validate its format.

Common objects

The same structures appear in many endpoints:

{
  "document": { "type": "CPF", "number": "12345678909" },
  "phone": { "areaCode": "+55", "ddd": "11", "number": "999999999", "isMobile": true },
  "address": {
    "zipCode": "01000000",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Suite 101",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  },
  "metadata": [{ "key": "orderReference", "value": "A-1001" }]
}

• document.type is CPF or CNPJ for buyers and customers. Participants also accept RG, CNH and INTERNATIONAL_ID. document.number contains only digits.
• address.state is the two-letter abbreviation of the Brazilian state.
• In Create charge, metadata is a list of key and value pairs that you can use to store your own references. Pixels use a metadata object instead.

Enumerations

Many enumerated values, such as payment methods and statuses, are lowercase and hyphenated, for example credit-card, bank-billet and partially-paid. Others follow different conventions: document types and state codes are uppercase (CPF, SP), orderDirection is ASC or DESC, and webhook events use dot notation (order.partiallyPaid). Always send the exact value and casing listed on each endpoint page.