Create Payin
POSTTag: api-payments-gateway-post-payinDescription: Create a new payin./v1/payin
Request
Header Parameters
- If there's no value: The default protection checks that the values in this request are equal: { method, params, path, query, body, userId }. This means that if a request repeats the same values, it will be blocked.
- 'nonce': The nonce and { method, params, path, query, body, userId } value are checked. When the protection schema is this, requests will be OK if this nonce value is different in each request.
- 'x-transaction-uuid': The transactionId and { method, params, path, query, body, userId } value are checked. Requests will be OK if this x-transaction-uuid value is different in each request.
- 'x-transaction-uuid&nonce' or 'nonce&x-transaction-uuid': The nonce, transactionId value and { method, params, path, query, body, userId } are checked, i.e. if requests are repeated the same value in both fields, they will be blocked. But if any field has a different value, the request is OK.
The replay-protection-schema allows the user to choose between 3 options:
Sender Wallet UUID (if empty, your default Wallet UUID will be settled)
The transaction ID is a UUID (v7) used to uniquely identify the object that will be created. All objects must have an identifier.
The nonce ID is a UUID (v4) used to uniquely identify the request. All requests must have an identifier.
Possible values: [pt-BR, en-US]
Indicates the preferred language. Defaults to Brazilian Portuguese if unspecified.
The product ID is a UUID (v4) used to identify the Z.ro product configuration.
The product target user ID is a UUID (v4) used to identify what user account this request must be executed. Require: x-product-uuid.
- application/json
Body
required
Payin creation request body. Choose one of the available payin method bodies.
- V1CreatePayinBody
- V1CreateAcquiringCreditPaymentBody
- V1CreateAcquiringDebitPaymentBody
- V1CreateCashDepositBody
- V1CreateBankTransferDepositBody
- MOD1
- MOD2
- MOD3
- MOD1
- MOD2
- MOD3
Possible values: [BRA, ARG, CHL, PER]
Country ISO 3166-1-alpha-3 code for the payment.
Possible values: [CREDIT_CARD, DEBIT_CARD, CASH, BANK_TRANSFER]
Payment method used in the transaction.
Payment amount in cents. Must be at least 100 cents.
Possible values: [PEN, CLP, ARS, USD, BRL]
Payment currency ISO 4217 code.
Third Part first name.
Third Part last name.
Third Part email address.
Third Part phone number.
Third Part document.
Possible values: [DNI, CE, PAS, PP, RUT, RUC, CUIL, CUIT, CPF, CNPJ]
Third Part document type.
User Address Zip Code.
User Address Street.
User Address number.
User Address City.
User Address State.
User Address Country.
User Address Complement.
User Address Neighborhood (for acquiring payments).
payment_card object
Card number.
Card CVV.
Card Holder Name.
Card Expiry Date in MM-YYYY format.
Number Of Installments. Allowed values: 1 to 12. Only for CREDIT payment method.
Language ISO 639-1 code for the payment.
Expiration time in minutes for the payment.
Possible values: [BRA, CHL, PER, ARG]
Country ISO 3166-1-alpha-3 code for the payment.
Possible values: [CREDIT_CARD]
Payment method used in the transaction.
Payment amount in cents. Min value is 1000 cents.
Possible values: [PEN, CLP, ARS, USD, BRL]
Payment currency ISO 4217 code
Third Part first name.
Third Part last name.
Third Part email address.
Third Part phone number.
Third Part document.
Possible values: [DNI, CE, PAS, PP, RUT, RUC, CUIL, CUIT, CPF, CNPJ]
Third Part document type.
Number Of Installments. Allowed values: 1 to 12.
payment_card object
Card number.
Card CVV.
Card Holder Name.
Card Expiry Date in MM-YYYY format.
User Address City.
User Address Country.
User Address number.
User Address state.
User Address Street.
User Address Zip Code.
User Address Complement.
User Address Neighborhood.
Whether to use redirect flow for payment processing. Default is true. If your company do not have a PCI certificate, you MUST send this field with "true"
URL to redirect after payment completion. Required when is_redirect is true or undefined.
Payment expiration time in minutes. Required when is_redirect is true or undefined.
Language for the payment interface. Required when is_redirect is true or undefined.
Possible values: [BRA, CHL, PER, ARG]
Country ISO 3166-1-alpha-3 code for the payment.
Possible values: [DEBIT_CARD]
Payment method used in the transaction.
Payment amount in cents. Min value is 1000 cents.
Possible values: [PEN, CLP, ARS, USD, BRL]
Payment currency ISO 4217 code
payment_card object
Card number.
Card CVV.
Card Holder Name.
Card Expiry Date in MM-YYYY format.
Third Part first name.
Third Part last name.
Third Part email address.
Third Part phone number.
Third Part document.
Possible values: [DNI, CE, PAS, PP, RUT, RUC, CUIL, CUIT, CPF, CNPJ]
Third Part document type.
User Address City.
User Address Country.
User Address number.
User Address state
User Address Street.
User Address Zip Code.
User Address Complement.
User Address Neighborhood.
3DS Authentication ID. Required for DEBIT payment method when is_redirect is false (direct flow). Optional when is_redirect is true (redirect flow).
Whether to use redirect flow for payment processing. Default is true. If your company do not have a PCI certificate, you MUST send this field with "true"
URL to redirect after payment completion. Required when is_redirect is true or undefined.
Payment expiration time in minutes. Required when is_redirect is true or undefined.
Language for the payment interface. Required when is_redirect is true or undefined.
Possible values: [CHL, PER, ARG]
Country ISO 3166-1-alpha-3 code for the payment.
Possible values: [CASH]
Payment method used in the transaction.
Payment amount in cents. Min value is 100 cents.
currency_tag object required
Payment currency ISO 4217 code
string
Possible values: [CLP]
string
Possible values: [PEN]
string
Possible values: [ARS]
Possible values: [pt, en, es]
Language ISO 639-1 code for the payment.
Expiration time in minutes for the payment. Default is 48 hours (2 days).
Third Part first name.
Third Part last name.
Third Part email address.
Third Part phone number.
Third Part document.
third_part_document_type object required
Third Part document type.
string
Possible values: [RUT, PP]
string
Possible values: [DNI, CE, PAS]
string
Possible values: [DNI, CUIT, CUIL]
User Address Zip Code.
User Address Street.
User Address number.
User Address City.
User Address State.
User Address Country.
User Address Complement.
Redirect URL for payment success and error.
Possible values: [CHL, PER, ARG]
Country ISO 3166-1-alpha-3 code for the payment.
Possible values: [BANK_TRANSFER]
Payment method used in the transaction.
Payment amount in cents. Min value is 100 cents.
Possible values: [CLP, PEN, ARS]
Payment currency ISO 4217 code
Third Part first name.
Third Part last name.
Third Part email address.
Third Part phone number.
Third Part document.
Possible values: [DNI, RUT, PAS, CE, RUC, CUIL, CUIT]
Third Part document type.
User Address Zip Code.
User Address Street.
User Address number.
User Address City.
User Address state.
User Address Country.
User Address Complement.
Expiration time in minutes.
Language.
Redirect URL for payment success and error.
CBU (Clave Bancaria Uniforme) for Argentina bank transfers.
CUIT (Código Único de Identificación Tributaria) for Argentina bank transfers.
Responses
- 200
- 400
- 401
- 422
Payin created successfully.
- application/json
- Schema
- Example (from schema)
Schema
Payin ID.
Payin status.
Payin creation date.
Payin update date.
{
"id": "0197b169-da6b-7ba2-b053-ce413ae39afd",
"status": "PENDING",
"created_at": "2025-10-22T15:30:01.715Z",
"updated_at": "2025-10-22T15:30:01.715Z"
}
If any required params are missing or has invalid format or type.
User authentication failed.
If any required params are missing or has invalid format or type.