Payin API (CHECKOUT)

Overview

The payin API creates a payin order to receive payments. Merchants can initiate payment requests to users, supporting the payment checkout method. Merchants can use this API to initiate payment requests to users, with the payment method being CVU transfer. Users fill in their identification information to place an order and call this API. They obtain the CVU account through the link returned by the API, transfer funds to that CVU, and after receiving the payment, the system will automatically match and complete the order using the identification number, amount, and expiration time.

Two Payin Modes

Argentina payin supports two modes that are mutually exclusive and cannot coexist. The merchant must confirm which mode to use before onboarding; each merchant supports only one mode. If you need both modes, please contact your account manager to open two merchants:

• Order Mode (this API): the merchant creates an order first; the user obtains a shared CVU via the checkout and transfers funds; the platform matches by ID number + amount + expiry;
• Independent CVU Mode (VA_DIRECT): the merchant owns an exclusively bound CVU; users transfer directly; the platform auto-creates the order and pushes an inbound details callback. This mode does not require calling this API. See Independent CVU Payin Callback.

API Info

• Endpoint: POST /api/ar/payin
• Method: POST
• Content-Type: application/json

Request Headers

All API requests require the following headers, see API Signature:

Header	Type	Required	Description
Content-Type	string	Y	application/json, fixed
MerchantId	string	Y	Merchant ID provided by Veloraya
Timestamp	string	Y	Current timestamp (ms), anti-replay
Nonce	string	Y	Random string, unique per request, anti-replay
Signature	string	Y	Request signature (RSA), Base64 encoded

Request Parameters

Parameter	Type	Required	Description
merchantOrderId	string	Y	Merchant order ID, unique
amount	BigDecimal	Y	Order amount, checked against merchant risk config
currency	string	Y	Currency code, fixed ARS
expireSeconds	Integer	N	Checkout expiry (seconds), 300s~86400s, default 24h
payinMethod	string	Y	Payment method, see enum
redirectUrl	string	N	Redirect URL after successful payment
payerEmail	string	Y	Payer email
payerIdType	string	Y	Payer ID type, fixed DNI
payerIdCard	string	Y	Payer ID number，this field must real.
payerFirstName	string	N	Payer first name
payerLastName	string	N	Payer last name
payerFullName	string	N	Payer full name (either this or firstName/lastName required)
payerMobile	string	Y	Payer mobile
needSecondaryConfirmation	boolean	N	Does this require secondary confirmation of user information, default true

Payment method enum

Value	Description
CHECKOUT	Payment checkout

ID type enum

Value	Description
DNI	Argentina national ID

Request Example

{
  "merchantOrderId": "ORDER46791673",
  "amount": 300,
  "currency": "ARS",
  "expireSeconds": 3600,
  "payinMethod": "CHECKOUT"
}

Response Format

Field	Type	Description
code	int	200 success, non-200 failure
msg	string	Response message
data	object	Response data, order info on success

Response Parameters (data)

Field	Type	Description
orderId	string	Platform order ID
merchantOrderId	string	Merchant order ID
amount	BigDecimal	Order amount
fee	BigDecimal	Transaction fee
payDeskUrl	string	Checkout URL
orderStatus	string	Order status
vaNumber	string	CVU account used for receiving payments. This parameter is returned when the request parameter needSecondaryConfirmation is false.
vaName	string	CVU account name used for receiving payments. This parameter is returned when the request parameter needSecondaryConfirmation is false.
resultCode	string	Error code (on failure)
resultDesc	string	Error description (on failure)

Order status enum

Value	Description
PENDING	Pending
FAILED	Failed

Response Example

Success

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "PAYIN48973464",
    "merchantOrderId": "ORDER46791673",
    "amount": 30000,
    "fee": 300.00,
    "payDeskUrl": "https://example.com/?orderNo=PAYIN48973464",
    "resultCode": null,
    "resultDesc": null,
    "orderStatus": "PENDING"
  }
}

Error Codes

See Error Codes for the full list.

Business Rules

1. Order ID uniqueness: merchant order IDs must be unique under the same merchant
2. Amount limit: checked against merchant risk config
3. Expiry: the checkout expires after expireSeconds, default 3600s
4. Async notification: order status changes are notified via Payin Callback (merchant must configure notify URL)
5. Risk control: orders are risk-checked; failures return an error

Notes

1. Headers: all required headers must be passed, see API Signature
2. Signature: all requests must include a valid signature
3. Async notification: order status changes are notified asynchronously
4. Idempotency: duplicate requests with the same merchant order ID return the same result and do not create duplicate orders
5. Timeout: set a reasonable request timeout
6. Logging: log all requests and responses