Skip to main content

Create Payin

POST 
/v1/payin
Tag: api-payments-gateway-post-payinDescription: Create a new payin payment request. This endpoint supports multiple payment methods including credit cards, debit cards, cash deposits, and bank transfers.Supported Payment Methods:• CREDIT_CARD: Credit card payments with acquiring integration • Brazil • Chile • Peru • Argentina • DEBIT_CARD: Debit card payments with acquiring integration • Brazil • Chile • Peru • Argentina • CASH: Cash deposit payments for physical locations • Chile • Peru • Argentina • BANK_TRANSFER: Bank transfer deposit payments • Chile • Peru • Argentina • OXXO: OXXO cash deposit payments • Mexico • YAPE: Yape wallet deposit payments • Peru • QR: QR code deposit payments • Peru • Chile • Argentina • ASTROPAY_BANK_TRANSFER: AstroPay bank transfer deposit payments • MexicoPayment Method Flow Details:1. Credit Card Payments (CREDIT_CARD):• Supports countries: Brazil, Chile, Peru, Argentina • Supports redirect flow for Non-PCI complient Merchants • Requires card information for direct flows • Supports installment payments (Brasil and Peru Only) • For special permissions, contact operations team for redirect or non-redirect flows2. Debit Card Payments (DEBIT_CARD):• Supports countries: Brazil, Chile, Peru, Argentina • For Brazil, it's required to use the 3DS authentication endpoint • Supports redirect flow for Non-PCI complient Merchants • Requires card information for direct flows • For special permissions, contact operations team for redirect or non-redirect flows3. Cash Deposit Payments (CASH):• Supports countries: Chile, Peru, Argentina • Generates payment instructions for physical payment • Default expiration time: 48 hours (2880 minutes)4. Bank Transfer Deposit Payments (BANK_TRANSFER):• Supports countries: Chile, Peru, Argentina • Generates bank transfer instructions • Default expiration time: 48 hours (2880 minutes)5. OXXO Cash Deposit Payments (OXXO):• Supports countries: Mexico • Generates payment instructions for OXXO stores • Default expiration time: 48 hours (2880 minutes) • Supported document types: RFC, CURP, PASSPORT, TAXSTATEMENT6. Yape Wallet Deposit Payments (YAPE):• Supports country: Peru • Generates Yape wallet instructions7. QR Code Deposit Payments (QR):• Supports countries: Peru, Chile, Argentina • Supports redirect flow (is_redirect=true): Redirects to external URL with QR code • Supports direct flow (is_redirect=false): Returns QR code URL and data directly • Generates QR code for payment • Default expiration time: 30 minutes (configurable)8. AstroPay Bank Transfer Deposit Payments (ASTROPAY_BANK_TRANSFER):• Supports countries: Mexico • Generates bank transfer instructions via AstroPay • Default expiration time: 48 hours (2880 minutes) • Supported document types: IDCARD, PASSPORT, TAXSTATEMENT • Requires virtual account IDCommon Requirements:• Minimum amount: 100 cents (1.00 in local currency) • Authentication required (Bearer token) • Wallet association required • Transaction ID for tracking • Country-specific permissions and validations • Language support (PT, EN, ES) • Requires third-party information (customer name, email, phone, document) • Requires complete address information • Supports different document types per countrySecurity Features:• Replay protection available • Permission-based access control • Country and product-specific permissionsResponse:Returns payment creation result with transaction details, status, and any URLs for payment instructions and/or checkout.

Request​

Header Parameters

    x-include-replay-protection-schema string

    The replay-protection-schema allows the user to choose between 3 options:

    • 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.

    x-wallet-uuid string

    Sender Wallet UUID (if empty, your default Wallet UUID will be settled)

    x-transaction-uuid stringrequired

    The transaction ID is a UUID (v7) used to uniquely identify the object that will be created. All objects must have an identifier.

    nonce stringrequired

    The nonce ID is a UUID (v4) used to uniquely identify the request. All requests must have an identifier.

    x-lang string

    Possible values: [pt-BR, en-US]

    Indicates the preferred language. Defaults to Brazilian Portuguese if unspecified.

    x-product-uuid string

    The product ID is a UUID (v4) used to identify the Z.ro product configuration.

    x-product-target-user-uuid string

    The product target user ID is a UUID (v4) used to identify what user account this request must be executed. Require: x-product-uuid.

Body

required

Payin creation request body. Choose one of the available payin method bodies.

    oneOf
    country stringrequired

    Possible values: [BRA, ARG, CHL, PER, MEX]

    Country ISO 3166-1-alpha-3 code for the payment.

    payment_method stringrequired

    Possible values: [CREDIT_CARD, DEBIT_CARD, CASH, BANK_TRANSFER, OXXO, YAPE, ASTRO_PAY_BANK_TRANSFER, QR]

    Payment method used in the transaction.

    amount_total numberrequired

    Payment amount in cents. Must be at least 100 cents.

    currency_tag object required

    Possible values: [MXN, PEN, CLP, ARS, USD, BRL]

    Payment currency ISO 4217 code.

    oneOf

    string

    Possible values: [BRL]

    third_part_name stringrequired

    Third Part first name.

    third_part_last_name stringrequired

    Third Part last name.

    third_part_email stringrequired

    Third Part email address.

    third_part_phone stringrequired

    Third Part phone number.

    third_part_document stringrequired

    Third Part document.

    third_part_document_type object required

    Possible values: [CPF, CNPJ, RUT, PP, DNI, CE, PAS, RUC, DNI, CUIT, CUIL, RFC, CURP, PASSPORT, TAXSTATEMENT]

    Third Part document type.

    oneOf

    string

    Possible values: [CPF, CNPJ]

    third_part_address_zip_code stringrequired

    User Address Zip Code.

    third_part_address_street stringrequired

    User Address Street.

    third_part_address_number stringrequired

    User Address number.

    third_part_address_city stringrequired

    User Address City.

    third_part_address_state stringrequired

    User Address State.

    third_part_address_country stringrequired

    User Address Country.

    third_part_address_complement string

    User Address Complement.

    third_part_address_neighborhood string

    User Address Neighborhood (for acquiring payments).

    payment_card object
    card_number stringrequired

    Card number.

    card_cvv stringrequired

    Card CVV.

    card_name stringrequired

    Card Holder Name.

    card_expiry_date stringrequired

    Card Expiry Date in MM-YYYY format.

    installments number

    Number Of Installments. Allowed values: 1 to 12. Only for CREDIT payment method.

    auto_capture boolean

    Whether to capture the payment value on success or later through the capture transaction endpoint. For card payments only (required for acquiring payments).

    language stringrequired

    Possible values: [pt, en, es]

    Language ISO 639-1 code for the payment.

    expiration_time_minutes number

    Expiration time in minutes for the payment.

    platform string

    Possible values: [WEB, MOBILE]

    Platform where the payment is being made (WEB or MOBILE).

    is_recurrent boolean

    Indicates if the payment is recurrent.

    is_redirect boolean

    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"

    redirect_url string

    Redirect URL for payment success and error.

    virtual_account_id string

    Virtual Account ID for AstroPay Bank Transfer.

Responses​

Payin created successfully.

Schema
    id stringrequired

    Payin ID.

    status stringrequired

    Payin status.

    created_at date-timerequired

    Payin creation date.

    updated_at date-timerequired

    Payin update date.

Loading...