Create Payin Order¶

Creates a new payin order.

Payin Order

A payin order is a payin operation created for a merchant gate payment method. Payin orders represent incoming funds from an external source to a merchant or gate balance.

Idempotency

Idempotency prevents duplicate payment requests by using the unique reference_id value.

Each reference_id should identify one payment request and must be unique within the merchant context. If the same reference_id is submitted again for the same context, the system can detect the request as a duplicate.

Use a newly generated UUID or another stable unique value for each new payment request, especially when generating reference_id values automatically.

Endpoint¶

POST /api/v1/orders/payin

POST /api/v1/orders/payin HTTP/1.1
X-Api-Key-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Signature: <generated-signature>
X-Timestamp: 1234567
Content-Type: application/json
Accept: application/json

{
  "reference_id": "merchant-order-12345",
  "currency": "USD",
  "amount": 100.00,
  "merchant_gate_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "payment_method_data": {
    "payment_url": "https://merchant.example/payment/12345"
  },
  "customer": {
    "reference_id": "customer-12345",
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+12025550123",
    "address": {
      "country": "FR",
      "city": "New York",
      "street": "Main Street 10",
      "post_code": "10001"
    }
  },
  "callback_url": "https://merchant.example/callbacks/payin",
  "return_urls": {
    "success": "https://merchant.example/payment/success",
    "pending": "https://merchant.example/payment/pending",
    "fail": "https://merchant.example/payment/fail"
  }
}

{
  "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. For signature generation rules, see Request Signature Authentication.

Request body for creating a payin order.

reference_id string required

Merchant-side order identifier. Use this value to match the created order with the corresponding order in the merchant system and to prevent duplicate payment requests.

Constraints: 0-255 characters; matches [A-Za-z0-9.=-]*

currency string required

Currency in which the payin order amount is processed.

Possible values:

USDEURUAHKZTUSDT_TRON

amount number required

Payin order amount.

Constraints: Use a dot as the decimal separator; maximum 2 decimal places.

merchant_gate_method_id string · uuid required

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

payment_method_data object optional

Additional payment method data used for the selected merchant gate payment method.

payment_url string optional

URL of the merchant website or payment page associated with the payment.

Constraints: 0-2048 characters

customer object required

Customer information associated with the payin order.

reference_id string optional

Customer identifier in the merchant system.

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

first_name string optional

Customer first name. Use Latin letters and supported special characters only.

Constraints: 0-50 characters; Latin letters, spaces, hyphens and apostrophes only.

last_name string optional

Customer last name. Use Latin letters and supported special characters only.

Constraints: 0-50 characters; Latin letters, spaces, hyphens and apostrophes only.

email string · email optional

Customer email address in a standard email format, such as local-part@domain. The value must contain a local part, the @ symbol, and a valid domain.

phone string optional

Customer phone number in international format. The value must start with + and contain digits after the country calling code.

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

address object optional

Customer address information.

country string optional

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

Example: FR

city string optional

Customer city name.

Constraints: 0-100 characters; Latin letters, digits, spaces, hyphens, and dots only.

street string optional

Customer street address.

Constraints: 0-255 characters; Latin letters, digits, spaces, hyphens, and dots only.

post_code string optional

Customer postal or ZIP code.

Constraints: 0-50 characters

callback_url string optional

Merchant callback URL used to receive the final status notification for the payin order.

Constraints: 0-355 characters

return_urls object optional

Merchant return URLs used to redirect the customer after the payment flow reaches a corresponding result.

success string optional

URL where the customer is redirected after a successful payment flow.

Constraints: 0-355 characters

pending string optional

URL where the customer is redirected when the payment flow remains pending.

Constraints: 0-355 characters

fail string optional

URL where the customer is redirected after a failed payment flow.

Constraints: 0-355 characters

Responses

200 OK. Payin order created successfully. application/json

Returns the created 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.

Create Payin Order¶

Endpoint¶

Headers

Request body

Responses