List Payin Orders¶

Returns a paginated list of payin orders.

Use this endpoint to retrieve payin orders by filter criteria such as group ID, date range, update date range, status, and currency.

Endpoint¶

GET /api/v1/orders/payin/list

GET /api/v1/orders/payin/list?page=1&size=10&sort=createDate,asc&groupId=3fa85f64-5717-4562-b3fc-2c963f66afa6&statuses=CREATED&statuses=SUCCESS HTTP/1.1
X-Api-Key-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Signature: <generated-signature>
X-Timestamp: 1234567
Accept: application/json

{
  "total_elements": 1,
  "total_pages": 1,
  "content": [
    {
      "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.

page integer required

Page number to retrieve. Use 1 for the first page.

Example: 1

size integer required

Number of orders to include in each page.

Example: 10

sort string optional

Sorting rule for the returned list. Use the format field,direction, where direction is asc or desc.

Example: createDate,asc

groupId string · uuid optional

Filters the list by order group identifier. If multiple orders are created together, they share the same group identifier. If the order is created separately, the group identifier is the same as the order ID.

startDate string · date-time optional

Filters the list by the start of the order creation date range.

endDate string · date-time optional

Filters the list by the end of the order creation date range.

startUpdateDate string · date-time optional

Filters the list by the start of the order update date range.

endUpdateDate string · date-time optional

Filters the list by the end of the order update date range.

statuses array<string> optional

Filters the list by one or more payin order statuses.

Items string · enum

Order status value.

Possible values:

CREATEDIN_PROGRESSPROCESS_PENDINGSUCCESSFAILEDCLOSED

currencies array<string> optional

Filters the list by one or more currencies in which the payin order amount is processed.

Items string · enum

Currency value.

Possible values:

USDEURUAHKZTUSDT_TRON

Using pagination

Use page and size to control which page of results is returned.

The page parameter is 1-based. Use page=1 to retrieve the first page, page=2 for the second page, and so on.

Use sort to define the sorting field and direction. The value uses the format field,direction, for example createDate,asc or createDate,desc.

Repeated query parameters can be used for multi-value filters, for example statuses=CREATED&statuses=SUCCESS.

The list endpoint does not use the id or reference_id filters.

Responses

200 OK. Payin orders returned successfully. application/json

Returns a paginated list of payin orders matching the provided filter criteria.

total_elements integer · int64

Total number of payin orders matching the filter criteria.

total_pages integer · int64

Total number of result pages available for the current filter and pagination parameters.

content array<object>

Array of payin order objects returned for the current page.

Items object

Payin order object.

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.

List Payin Orders¶

Endpoint¶

Headers

Query parameters

Responses