Get Payin Orders by Reference ID¶

Returns payin orders by the merchant-side order reference identifier.

Use this endpoint when you need to retrieve one or more payin orders associated with the same reference_id value in the merchant system.

Endpoint¶

GET /api/v1/orders/payin?reference_id={reference_id}

GET /api/v1/orders/payin?reference_id=merchant-order-12345 HTTP/1.1
X-Api-Key-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Signature: <generated-signature>
X-Timestamp: 1234567
Accept: application/json

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "seq_id": 1024,
    "reference_id": "merchant-order-12345",
    "status": "SUCCESS",
    "resolution": "OK",
    "resolution_code": "WORKFLOW_EXECUTION_SKIPPED",
    "resolution_message": "Order processed successfully.",
    "provider_error_message": "",
    "payment_source": "CARD",
    "currency": "USD",
    "amount": 100.00,
    "payment_method_currency": "USD",
    "payment_method_amount": 100.00,
    "conversion_rate": 1,
    "fee_percent": 1,
    "fee_fixed": 3,
    "fee_min": 1,
    "fee_max": 7,
    "fee_total": 4,
    "total": 96,
    "hold_amount": 0,
    "settlement_period": 0,
    "rolling_percent": 0,
    "rolling_amount": 0,
    "merchant_gate_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "payment_method_data": {
      "bank_id": "bank_001",
      "cpf": "27019229541",
      "iban": "GB82WEST12345698765432",
      "ifsc": "ifsc_001",
      "pix_key": "customer@example.com",
      "tckn": "37621909054"
    },
    "card_number": "411111******1111",
    "customer": {
      "reference_id": "customer-12345",
      "first_name": "John",
      "last_name": "Doe",
      "email": "user@example.com",
      "phone": "+12025550123",
      "address": {
        "country": "FR",
        "city": "Paris",
        "street": "Main Street 10",
        "post_code": "75001"
      }
    },
    "pay_url": "https://payment.example/pay/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "return_url": "https://merchant.example/payment/success",
    "rrn": "123456789012",
    "create_date": 1783705454,
    "update_date": 1783705454,
    "comment": "Merchant order comment."
  }
]

X-Api-Key-Id string · uuid required

API key identifier issued for the merchant integration.

X-Signature string required

Request signature generated from the HTTP method, request path without query string, raw request body, and timestamp.

X-Timestamp integer · int64 required

Unix epoch timestamp in seconds used in the signature base string.

Request signature

This endpoint requires the X-Signature header. This GET request has no request body, so the signature base string uses an empty request body value. For signature generation rules, see Request Signature Authentication.

reference_id string required

Merchant-side order reference identifier. Use this parameter to retrieve payin orders created with the specified reference value.

Responses

200 OK. Payin orders returned successfully. application/json

Returns an array of payin order objects matching the provided reference ID.

Items array<object>

Payin order object returned in the response array.

id string · uuid

System-generated unique payin order identifier. Use this value to retrieve a specific payin order by ID.

group_id string · uuid

Identifier used to group related orders. Orders created or processed as part of the same operation can share this value.

seq_id integer · int64

Sequential numeric identifier of the payin order.

reference_id string

Order reference identifier provided by the merchant system. Use this value to match the created order with the corresponding order in the merchant system.

status string · enum

Current payin order processing status.

Possible values:

CREATEDIN_PROGRESSPROCESS_PENDINGSUCCESSFAILEDCLOSED

resolution string · enum

High-level processing resolution for the order.

Possible values:

OKSYSTEM_ERRORPROVIDER_ERROR

resolution_code string · enum

Machine-readable resolution reason code returned for the order.

Possible values:

ACCESS_DENIEDAMOUNT_OVER_LIMITAMOUNT_UNDER_LIMITBALANCE_INSUFFICIENTBALANCE_UPDATE_FAILEDBLACKLISTED_INPUT_DATACURRENCY_INVALIDDESTINATION_ACCOUNT_INVALIDMERCHANT_MISCONFIGURATIONMETHOD_INACTIVEMETHOD_NOT_FOUNDORDER_CANNOT_BE_PROCESSEDORDER_CANNOT_BE_ROUTEDORDER_FAILED_MANUALLYPAYMENT_METHOD_NOT_SUPPORTEDPROVIDER_NOT_SUPPORTEDREPORT_GENERATION_FAILEDRESOURCE_NOT_FOUNDUNKNOWN_ERRORVALIDATION_FAILEDWORKFLOW_EXECUTION_SKIPPED

resolution_message string

Human-readable message with additional details about the order resolution.

provider_error_message string

Error message returned by the payment provider, if available.

payment_source string · enum

Payment source used for the order.

Possible values:

CARDP2PCRYPTOPHONEPIXBLIK

currency string · enum

Original order currency.

Possible values:

USDEURUAHKZTUSDT_TRON

amount number

Original payin order amount in the order currency.

payment_method_currency string · enum

Currency used by the selected payment method. This can differ from currency when conversion is applied.

Possible values:

USDEURUAHKZTUSDT_TRON

payment_method_amount number

Order amount expressed in the payment method currency. This can differ from amount when conversion is applied.

conversion_rate number

Exchange rate used to convert the order amount to the payment method currency.

fee_percent number

Percentage-based fee rate applied to the order amount.

fee_fixed number

Fixed fee amount charged for the order.

fee_min number

Minimum fee amount that can be applied to the order.

fee_max number

Maximum fee amount that can be applied to the order.

fee_total number

Final fee amount calculated for the order after applying percentage, fixed, minimum, and maximum fee rules.

total number

Calculated payin total after fee calculation. Use amount for the original order amount and fee_total for the calculated fee.

hold_amount number

Amount placed on hold during the settlement period.

settlement_period number

Number of days funds remain on hold before becoming available.

rolling_percent number

Percentage of the order amount allocated to rolling reserve.

rolling_amount number

Amount allocated to rolling reserve for the order.

merchant_gate_method_id string · uuid

Identifier of the merchant gate payment method used to process the payin order.

merchant_id string · uuid

Identifier of the merchant associated with the order.

payment_method_data object

Payment-method-specific data returned for the order.

bank_id string

Bank identifier used by a payment method or provider.

Constraints: Matches ^[a-z0-9_-]{1,200}$

cpf string

CPF value used for payment methods that require CPF.

Constraints: Matches ^[0-9]{11}$

iban string

IBAN value used for bank transfer or account-based payment methods.

Constraints: Matches ^[A-Z0-9]{15,36}$

ifsc string

IFSC value used for payment methods that require IFSC.

Constraints: Matches ^[a-z0-9_-]{1,200}$

pix_key string

PIX key used for PIX-based payment methods.

Constraints: 0-1024 characters

tckn string

TCKN value used for payment methods that require TCKN.

Constraints: Matches ^[0-9]{11}$

card_number string

Masked card number associated with the payin order, when available.

customer object

Customer information associated with the order.

reference_id string

Customer identifier in the merchant system.

Constraints: Matches ^[a-zA-Z0-9_-]{1,64}$

first_name string

Customer first name.

Constraints: Matches ^[\p{L} .'-]+$; 0-50 characters

last_name string

Customer last name.

Constraints: Matches ^[\p{L} .'-]+$; 0-50 characters

email string · email

Customer email address.

phone string

Customer phone number in international format.

Constraints: Matches ^\+[0-9]{5,30}$

address object

Customer address information.

country string

Two-letter country code in ISO 3166-1 alpha-2 format.

Example: FR

city string

Customer city.

Constraints: Matches ^[\p{L} .'-]+$; 0-100 characters

street string

Customer street address.

Constraints: 0-255 characters

post_code string

Customer postal code.

Constraints: 0-50 characters

pay_url string

Payment page URL used by the customer to complete the payin order.

return_url string

Merchant return URL associated with the payin order.

rrn string

Retrieval Reference Number returned for the payment, when available.

create_date integer · int64

Unix timestamp in seconds indicating when the order was created.

update_date integer · int64

Unix timestamp in seconds indicating when the order was last updated.

comment string

Comment associated with the order.

Get Payin Orders by Reference ID¶

Endpoint¶

Headers

Query parameters

Responses