Create Payment

Making a Request

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

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, no spaces or dashes	Partial
`card_security_code`	string	Security code (CVV/CVC)	Partial
`card_holder_document`	string	Cardholder document (CPF or CNPJ, numbers only)	Yes
`card_holder_name`	string	Cardholder name as printed on the card	Yes
`installments`	integer	Number of installments (between 1 and 12). If not provided, defaults to 1 installment.	No
`payment_type`	string	Payment type (CREDIT or DEBIT). If not provided, defaults to CREDIT.	No
`currency`	string	Transaction currency (BRL). If not provided, defaults to BRL.	Yes
`amount`	integer	Payment amount in cents (e.g.: `100` = R$ 1.00)	Yes
`reference_code`	string	Unique external identifier generated by the client	No
`platform_name`	string	Name of the platform generating the checkout	No
`billing_url`	string	URL to redirect the user to the custom billing page	No
`return_url`	string	Webhook URL where notifications will be sent	No
`threeds_data`	object	3D Secure data for transaction authentication	Yes
`threeds_data.operation_session_id`	string	Created 3DS session ID	Yes
`threeds_data.xid`	string	Authentication transaction ID included by the MPI for the merchant (may contain special characters). Must only be sent for 3DS authentication service usage. Field used only for Visa brand.	Yes
`threeds_data.cavv`	string	Cryptogram code used in transaction authentication and sent by the merchant's MPI (may contain special characters).	Yes
`threeds_data.eci`	string	Code returned to the MPI by card brands indicating the cardholder authentication result with the Issuer. Debit transactions must be authenticated.	Yes
`threeds_data.secure_version`	string	3DS version used in the authentication process by the MPI.	Yes
`threeds_data.directory_server_transaction_id`	string	Authentication transaction ID included by the MPI for the merchant (may contain special characters). Must only be sent for 3DS authentication service usage.	Yes
`threeds_data.three_ds_server_transaction_id`	string	3DS server transaction ID generated during authentication.	Yes
`billing_address`	object	Billing address data (For transactions of R$150.00 or above)	No
`billing_address.street`	string	Billing address street	No
`billing_address.number`	string	Billing address number	No
`billing_address.neighborhood`	string	Billing address neighborhood	No
`billing_address.city`	string	Billing address city	No
`billing_address.state`	string	Billing address state	No
`billing_address.zip_code`	string	Billing address ZIP code	No
`billing_address.complement`	string	Billing address complement	No

Request Example (Standard)

POST /v1/card_payments

HTTP Request Body
{
    "card_payment": {
        "reference_code": "string",
        "amount": 100,
        "currency": "BRL",
        "payment_type": "CREDIT",
        "card_expiration_date": "string",
        "card_number": "string",
        "card_security_code": "string",
        "card_holder_name": "string",
        "card_holder_document": "string",
        "installments": 1,
        "threeds_data": {
            "operation_session_id": "string",
            "cavv": "string",
            "xid": "string",
            "eci": "string",
            "secure_version": "string",
            "directory_server_transaction_id": "string",
            "three_ds_server_transaction_id": "string"
        }
    }
}

Request Example (R$150.00 or above)

POST /v1/card_payments

HTTP Request Body
{
    "card_payment": {
        "reference_code": "string",
        "amount": 15000,
        "currency": "BRL",
        "payment_type": "CREDIT",
        "card_expiration_date": "string",
        "card_number": "string",
        "card_security_code": "string",
        "card_holder_name": "string",
        "card_holder_document": "string",
        "installments": 1,
        "billing_address": {
            "street": "string",
            "number": "string",
            "neighborhood": "string",
            "city": "string",
            "state": "string",
            "zip_code": "string",
            "complement": "string"
        },
        "threeds_data": {
            "operation_session_id": "string",
            "cavv": "string",
            "xid": "string",
            "eci": "string",
            "secure_version": "string",
            "directory_server_transaction_id": "string",
            "three_ds_server_transaction_id": "string"
        }
    }
}

Request Example (Zero Dollar) → Card Validation

POST /v1/card_payments

HTTP Request Body (Zero Dollar) - Card Validation - Example
{
    "card_payment": {
        "reference_code": "string",
        "amount": 0,
        "currency": "BRL",
        "payment_type": "CREDIT",
        "card_expiration_date": "string",
        "card_number": "string",
        "card_security_code": "string",
        "card_holder_name": "string",
        "card_holder_document": "string",
        "installments": 1,
        "threeds_data": {
            "operation_session_id": "string",
            "cavv": "string",
            "xid": "string",
            "eci": "string",
            "secure_version": "string",
            "directory_server_transaction_id": "string",
            "three_ds_server_transaction_id": "string"
        }
    }
}

Success

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

HTTP 201 Response Body - Example
{
    "data": {
        "message": "Payment approved.",
        "status": "created",
        "status_details": "accepted"
    }
}

Notified Events

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

Visit this page for more details about Webhook - Card Notification

Errors

In case of errors, a JSON will be returned with the error attribute specifying 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`	Unique external identifier, created by the client
`amount`	Transaction amount
`rrn`	Retrieval Reference Number (acquirer/bank reference)
`status`	Transaction response code (`accepted`, `reject`, and `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 digits of the card
`installments`	Number of installments
`created_at`	Transaction creation date/time
`code`	Transaction error code (found within the `errors` array)
`msg`	Returned error description (found within 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 – API authentication/authorization failure
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 card expiration date month is invalid.
INCORRECT_EXPIRATION_DATE	Incorrect expiration date. Correct format is MMyyyy.	When the card expiration date does not match 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 the amount field.
CURRENCY_REQUIRED	Currency required.	Transaction without the currency field.
FIELDS_REQUIRED	The following fields are required: expirationDate	When attempting 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 attempting to send a transaction, check the supported currency.
CURRENCY_INVALID_FORMAT	Currency must be notated in ISO 4217 currency code.	When attempting 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	Amounts 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 attempting to send a transaction, check that the total split value cannot be equal to or greater than the transaction amount.
EMPTY_SPLIT	Field splits can't be empty if splitValueType field is present	When attempting to send a transaction, check 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 attempting 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 attempting to send a transaction, a duplicated documentId is not allowed.
INVALID_INSTALLMENTS_PLAN_ENTRY	Installments plan entry cannot be the same as or lower than the previous entry.	When attempting to send a transaction, the installment plan entry value must not be equal to or lower than the previous entry.
INSTALLMENTS_PLAN_ENTRIES_AND_INSTALLMENTS_MISMATCH	InstallmentsPlan should have the same amount of entries as the installments field value.	When attempting to send a transaction, the installment plan must have the same number of entries as the installments field value.
INSTALLMENTS_PLAN_CANT_BE_EMPTY	Installments plan cannot be empty.	When attempting 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 attempting to send a transaction, null or 0 (zero) installments are not allowed.
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 attempting 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 attempting to send a transaction, more than 20 split entries are not allowed.

Making a Request​

Request Example (Standard)​

Request Example (R$150.00 or above)​

Request Example (Zero Dollar) → Card Validation​

Success​

Notified Events​

Errors​

🔹 Important Response Attributes​

🔹 Response Codes​

Gateway Error Table​