Create Payment

Making Request

The call must be made using the POST method. Authentication via Authorization header is required.

POST/v1/card_payments

Attribute Description

Attribute	Type	Description	Required
`card_expiration_date`	string	Card expiration date, in MMyyyy format (e.g.: `012029`)	Partial
`card_number`	string	Card number, without spaces or dashes	Partial
`card_security_code`	string	Security code (CVV/CVC)	Partial
`slug_token`	string	A 32-character alphanumeric sequence representing a tokenized card by the `/v1/tokenize_card` endpoint. Can be used instead of `card_number`, `card_expiration_date` and `card_security_code`.	No
`slug_stored_card`	string	A 32-character alphanumeric sequence representing a card stored in the card vault by the `/v1/tokenize_card` endpoint. Can be used instead of `card_number`, `card_expiration_date` and `card_security_code`.	No
`card_holder_document`	string	Card holder document (CPF or CNPJ, numbers only)	Yes
`card_holder_name`	string	Holder name printed on the card	Yes
`installments`	integer	Number of installments (between 1 and 12)
If not sent, default is 1 installment	No
`payment_type`	string	Payment type (CREDIT or DEBIT)
If not sent, default is CREDIT	No
`currency`	string	Transaction currency (BRL)
If not sent, default is BRL	Yes
`amount`	integer	Payment amount in cents (e.g.: `100` = R$ 1.00)	Yes
`platform_name`	string	Platform name generating the checkout	No
`billing_url`	string	URL to redirect the user to the customized billing page	No
`return_url`	string	Webhook URL where notifications will be sent	No

Request Example (Standard)

POST /v1/card_payments

HTTP Request Body
{
  "card_payment": {
    "card_expiration_date": "012029",
    "card_holder_document": "00000000000",
    "card_security_code": "123",
    "card_holder_name": "John Doe",
    "installments": 1,
    "payment_type": "CREDIT",
    "card_number": "4111111111111111",
    "currency": "BRL",
    "amount": 100,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string"
  }
}

Request Example (Zero Dollar) → Card Validation

POST /v1/card_payments

HTTP Request Body (Zero Dollar) - Card Validation - Example
{
  "card_payment": {
    "card_expiration_date": "012029",
    "card_security_code": "123",
    "card_holder_name": "John Doe",
    "card_holder_document": "00000000000",
    "card_number": "4111111111111111",
    "amount": 0,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string"
  }
}

Request Example (Slug Token)

POST /v1/card_payments

HTTP Request Body Slug Token - Example
{
  "card_payment": {
    "slug_token": "XXXXXXXXXXX",
    "card_holder_document": "00000000000",
    "card_holder_name": "John Doe",
    "installments": 1,
    "payment_type": "CREDIT",
    "currency": "BRL",
    "amount": 100,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string"
  }
}

Request Example (Stored Card)

POST /v1/card_payments

HTTP Request Body Stored Card - Example
{
  "card_payment": {
    "slug_stored_card": "XXXXXXXXXXX",
    "card_holder_document": "00000000000",
    "card_holder_name": "John Doe",
    "installments": 1,
    "payment_type": "CREDIT",
    "currency": "BRL",
    "amount": 100,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string"
  }
}

Success

After the call, a JSON is returned with status 201 - Created if the procedure was successful.

HTTP 201 Response Body - Example
{
  "card_payment": {
    "muid": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "external_id": "your-external-id",
    "slug": null,
    "rrn": "123456789012",
    "amount": 1000,
    "currency": "BRL",
    "status": "approved",
    "last_digits": "4321",
    "installments": 2,
    "tracking_number": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "card_holder_name": "John Doe",
    "card_holder_email": null,
    "card_holder_document": "12345678901",
    "brand": "Visa",
    "request_token": "req_tok_abc123xyz",
    "payment_type": "credit",
    "authorization_code": "A1B2C3",
    "refund_tracking_number": null,
    "first_digits": "411111",
    "active": true,
    "slug_authorizer": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "slug_customer": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "slug_terminal": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "slug_merchant": "7bcedaa6-1c58-4ae6-a7ca-3c4628967049",
    "sales_channel": null,
    "authorizer_merchant_id": "M1234567",
    "authorizer_terminal_id": "T7654321",
    "transaction_status": "authorized",
    "product_or_issuer": null,
    "settlement_management_type": null,
    "transaction_method": "",
    "cancelling": false,
    "platform_name": "string",
    "billing_url": "string",
    "return_url": "string",
    "created_at": "2025-09-11T19:45:00Z"
  }
}

Notified Events

The system will send notifications for all available transaction statuses.
This applies to Checkout, PixQrCode, and Card transactions.
Any status change (Creation, confirmation, cancellation, etc.) will result in a call to the webhook configured during the transaction's creation.
The notifications will follow the exact same data pattern already used by the existing webhook, ensuring compatibility and consistency in the integration.

For more details, please refer to Webhook - Notification for Card Payment

Errors

In case of errors, a json will be returned with the error attribute specifying the reason why the operation was invalidated.

HTTP 422 Response Body - Unprocessable Entity - Example
  {
    "errors": [
        {
            "code": "AUTHORIZER_REJECTED",
            "msg": "46 - Identification required"
        }
    ],
    "muid": "f251e1b753504766957cf4142e936262",
    "request_token": "83329FF45587498D88E1590C7FB78CD8",
    "amount": 1,
    "currency": "BRL",
    "tracking_number": "00010609171144580010000000324834",
    "last_digits": "1111",
    "transaction_status": "REJECTED",
    "brand_response_code": "83",
    "multiacq_id": "021"
}

🔹 Important Response Attributes

Attribute	Description
`muid`	Unique transaction identifier
`external_id`	External unique identifier created by the client
`amount`	Transaction amount
`rrn`	Retrieval Reference Number (acquirer/bank reference)
`status`	Transaction response code (`accepted`, `reject`, `waiting_3ds_authentication`)
`transaction_status`	Transaction status (`pending`, `pre_authorized`, `authorized`, `denied`, `canceled`, `expired`, `refunded`, `waiting`)
`authorization_code`	Authorization code returned by the acquirer
`last_digits`	Last 4 card digits
`installments`	Number of installments
`created_at`	Transaction creation date/time
`code`	Transaction error code (found inside the `errors` array)
`msg`	Error description returned (found inside the `errors` array)

🔹 Response Codes

200 OK – Payment processed successfully
422 Unprocessable Entity – Invalid data (e.g.: incorrect CPF format or card number)
401 Unauthorized – Authentication/authorization failure in the API
500 Internal Server Error – Internal processing error

Gateway Error Table

Error Code	Message	Description
MIN_INSTALLMENTS	Installments can't be lower than 1	The number of installments cannot be less than 1.
MAX_INSTALLMENTS	Installments can't the higher than 12	The number of installments cannot be greater than 12.
INVALID_MONTH_NUMBER	Incorrect expiration date. Invalid month number.	When the month of the card expiration date is invalid.
INCORRECT_EXPIRATION_DATE	Incorrect expiration date. Correct format is MMyyyy.	When the card expiration date is different from the correct format (mmYYYY).
EXPIRATION_DATE_NON_NUMERIC	Expiration date has non-numeric character.	When the card expiration date has non-numeric characters.
MSG_GENERAL_ERROR	Unknown Card Brand.	When the card number has more than 19 digits or is empty.
AMOUNT_REQUIRED	Amount required.	Transaction without sending the amount field.
CURRENCY_REQUIRED	Currency required.	Transaction without sending the currency field.
FIELDS_REQUIRED	The following fields are required: expirationDate	When trying to send a transaction, check the expiration date.
INVALID_CVV	Invalid CVV. CVV should be 3 digits.	When the card security code is different from 3 digits (except AMEX) and/or is not numeric.
CURRENCY_NOT_SUPPORTED	Currency not supported. Please refer to our documentation to see supported currencies.	When trying to send a transaction, check the supported currency.
CURRENCY_INVALID_FORMAT	Currency must be notated in ISO 4217 currency code.	When trying to send a transaction, check the supported currency format.
INVALID_AMOUNT	Invalid Amount	The amount field is invalid.
AMOUNT_NOT_SUPPORTED	Amount can't be higher than 100 million	Values greater than 100 million are not supported.
AMOUNT_OUT_OF_BOUNDS	Amount value out of bounds (max 2 digits expected for fraction)	When the amount has more than two digits after the decimal point.
SPLIT_VALUE_TOO_HIGH	Splits total value can't be equal or higher than the transaction amount.	When trying to send a transaction, verify that the total value of splits cannot be equal to or greater than the transaction amount.
EMPTY_SPLIT	Field splits can't be empty if splitValueType field is present	When trying to send a transaction, verify that the splits field cannot be empty if the splitValueType field is present.
EMPTY_SPLIT_TYPE	Field splitValueType can't be empty if splits field is present	When trying to send a transaction, the splitValueType field cannot be empty if the splits field is present.
OWNER_IN_SPLIT	Merchant executing the transaction must not be on splits field	If you are the one executing the split, you should not be included in the split field.
SPLIT_MERCHANT_DUPLICATION	Can't have duplicated documentId in split	When trying to send a transaction, you cannot have a duplicated documentId.
INVALID_INSTALLMENTS_PLAN_ENTRY	Installments plan entry cannot be the same as or lower than the previous entry.	When trying to send a transaction, the installment plan entry value should not be the same as or lower than the previous entry.
INSTALLMENTSPLAN_ENTRIES_AND_INSTALLMENTSMISMATCH	InstallmentsPlan should have the same amount of entries as the installments field value.	When trying to send a transaction, the installment plan should have the same number of entries as the installments field value.
INSTALLMENTS_PLAN_CANT_BE_EMPTY	Installments plan cannot be empty.	When trying to send a transaction, the installment plan cannot be empty.
INVALID_NULL_OR_ZERO_INSTALLMENTS_PLAN_ENTRY	Installments plan entries cannot be null nor 0 (zero).	When trying to send a transaction, you cannot send null or 0 (zero) installments.
CUSTOM_NOT_ALLOWED	Customer not allowed for custom installment plan transaction.	Customer not allowed for custom installment plan transaction.
CARDBRAND_NOT_ALLOWED	Cardbrand must be Visa for custom installment plan transactions.	The card brand must be Visa for custom installment plan transactions.
MSG_GENERAL_ERROR	These documentId were not found: "S"	document_id not found.
MSG_GENERAL_ERROR	The following merchants aren't enabled to process CNP with authorizer POSTILION: "S"	Merchant not enabled to process CNP.
Split value must be higher than zero	Split value must be higher than zero	When trying to send a transaction, the split value must be greater than zero.
Can't have more than 20 splits entries	Can't have more than 20 splits entries	When trying to send a transaction, you cannot have more than 20 split entries.

Making Request​

Request Example (Standard)​

Request Example (Zero Dollar) → Card Validation​

Request Example (Slug Token)​

Request Example (Stored Card)​

Success​

Notified Events​

Errors​

🔹 Important Response Attributes​

🔹 Response Codes​

Gateway Error Table​