Skip to main content

Get Payin by ID

GET 
/v1/payin/:id
Tag: api-payments-gateway-get-payin-by-idDescription: Retrieve payin payment details by its unique ID. This endpoint requires the payment method type to be specified in the query parameter to determine the appropriate response format and data structure.Required Parameters:• id (path parameter): Unique identifier of the payin transaction • type (query parameter): Payment method type - REQUIRED to specify the payment methodSupported Payment Method Types:• CREDIT_CARD: Credit card payment details with acquiring information • DEBIT_CARD: Debit card payment details with acquiring information • CASH: Cash deposit payment details with third-party information • BANK_TRANSFER: Bank transfer deposit payment details with transfer instructions • OXXO: OXXO cash deposit payment detailsResponse Details by Payment Method:1. Acquiring Payments (CREDIT_CARD/DEBIT_CARD):• Returns acquiring transaction details • Includes payment status, amount, currency • Shows card information (masked/encrypted) • Contains acquiring provider details • Includes 3DS authentication status if applicable • Shows installment information for credit cards • Returns redirect URLs if applicable2. Cash Deposit Payments (CASH):• Returns cash deposit transaction details • Shows payment instructions and location details3. Bank Transfer Deposit Payments (BANK_TRANSFER):• Returns bank transfer deposit transaction details • Shows bank transfer instructions and account detailsCommon Response Fields:• Payment ID and operation ID • Transaction status and timestamps • Amount and currency information • User and wallet associations • Country and language settings • Error messages and validation status • Includes third-party information (name, email, phone, document) • Contains expiration time and status • Includes address information • Shows document type and validation statusImportant Notes:• The type parameter is MANDATORY and must match the original payment method • Authentication and wallet permissions are required • Only the payment owner can retrieve their payment details • Response format varies based on the payment method specified in the type parameterSecurity Features:• User authentication required (Bearer token) • Wallet association validation • Payment ownership verification • Sensitive data masking/encryption • Audit logging for access tracking

Request​

Path Parameters

    id stringrequired

    Payin ID

Query Parameters

    type stringrequired

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

    Payment method type

Header Parameters

    x-wallet-uuid string

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

    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.

Responses​

Payin details retrieved successfully.

Schema
    oneOf
    id stringrequired

    Payment ID.

    operation_id string

    Operation ID associated with the transaction.

    country stringrequired

    Country Of Transaction.

    sales_channel string

    Possible values: [POS, PDV, MPOS, PAYLINK, INTEGRATION, TAP_ON_PHONE, VIRTUAL_TERMINAL]

    Payment Sales Channel.

    payment_method stringrequired

    Possible values: [DEBIT_CARD, CREDIT_CARD]

    Payment Method.

    amount numberrequired

    Payment Value.

    currency_tag stringrequired

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

    Payment Currency Tag.

    status stringrequired

    Possible values: [PENDING, WAITING, WAITING_THREE_DS, AUTHORIZED, EXPIRED, DECLINED, REVERTED, CANCELLATION_IN_PROGRESS, CANCELLED, SETTLED, REFUNDED, FAILED, ERROR]

    Transaction Status.

    third_part_name stringrequired

    Third Part Full Name.

    third_part_last_name string

    Third Part Last Name.

    third_part_email stringrequired

    Third Part Email Address.

    third_part_phone_number stringrequired

    Third Part Phone Number.

    third_part_document_type stringrequired

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

    Third Part Document Type.

    third_part_document stringrequired

    Third Part Document Number.

    third_part_address_city stringrequired

    Third Part Address City.

    third_part_address_country stringrequired

    Third Part Address Country.

    third_part_address_federative_unit stringrequired

    Third Part Address Federative Unit.

    third_part_address_number stringrequired

    Third Part Address Number.

    third_part_address_street stringrequired

    Third Part Address Street.

    third_part_address_zip_code stringrequired

    Third Part Address Zip Code.

    third_part_address_complement string

    Third Part Address Complement.

    third_part_address_neighborhood string

    Third Part Address Neighborhood.

    card_last_four_digits string

    Last four digits of the card used.

    installments numberrequired

    Number of installments for the transaction.

    authorized_date date-time

    Transaction Confirmation Date.

    declined_date date-time

    Transaction Declined Date.

    cancelled_date date-time

    Transaction Cancelled Date.

    settlement_date date-time

    Transaction Settled Date.

    cancelled_max_date date-time

    Transaction Cancelled Max Date.

    refunded_max_date date-time

    Transaction Refunded Max Date.

    expected_settlement_date date-time

    Expected External Settlement Date.

    settled_acquiring_transactions object[]

    Settled Acquiring Transactions

  • Array [
    • id stringrequired

    Settled Transaction ID.

    amount numberrequired

    Settled Transaction Amount.

    installment_number number

    Installment Number.

    created_at date-timerequired

    Transaction Creation Date.

  • ]
    • acquiring_transaction_refunds object[]

    Acquiring Transaction Refunds

  • Array [
    • id stringrequired

    Refund Transaction ID.

    amount numberrequired

    Refund Transaction Amount.

    status stringrequired

    Possible values: [PENDING, WAITING, ACCEPTED, DECLINED, FAILED, ERROR]

    Refund Transaction Status.

    accepted_date date-time

    Refund Accepted Date.

    declined_date date-time

    Refund Declined Date.

    failed_date date-time

    Refund Failed Date.

    created_at date-timerequired

    Refund Creation Date.

  • ]
    • payment_url string

    Url to provide to customer to continue the payment.

    redirect_url string

    Redirect URL for payment success and error.

    expiration_time_minutes number

    Expected time in minutes for transaction expiration.

    language string

    Language code for the transaction, e.g., "en", "pt".

    expiration_date date-time

    Transaction Expiration Date.

    created_at date-timerequired

    Transaction creation date

    updated_at date-timerequired

    Transaction last update date

Loading...