Independent CVU Payin Callback API

Overview

In Independent CVU mode, a merchant owns an exclusively bound receiving CVU. After an end user transfers funds directly to that CVU, Veloraya receives the inbound callback, automatically creates a payin order, completes settlement/accounting, and then pushes the inbound details (including payer CUIT, bank transaction ID, etc.) to the merchant via this callback. The merchant uses these details to credit the user.

Differences from the Order-mode payin callback:

Item	Order-mode Payin Callback	Independent CVU Payin Callback
Order required first	Yes, merchant calls Create Payin Order	No, platform auto-creates the order
Callback URL	Merchant configures payin callback URL in merchant admin	Merchant configures VA inbound callback URL in merchant admin
Order ID source	Merchant-provided merchantOrderId	Platform-generated; merchantOrderId = platform order ID
Core matching key	ID number + amount + expiry	Operated by the merchant
Payer ID	DNI (prefix/suffix stripped)	Full CUIT (11 digits)

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

Callback URL Configuration

The Independent CVU callback uses a separate URL vaNotifyUrl, independent from the payin callback URL payinNotifyUrl:

• Configured by operations staff in the merchant-admin Access Configuration page (same page and save flow as the payin callback URL);
• If vaNotifyUrl is not configured, the platform only logs and does not push or alert. Ensure it is configured before go-live.

Callback Mechanism

Trigger conditions

• The platform receives a CVU inbound callback that hits a merchant's exclusively bound CVU;
• Triggered after auto order creation and settlement/accounting complete.

Retry mechanism

Item	Description
Max retries	11 times (including the first push)
Interval	30 seconds (first 6 retries)
Interval	3 minutes (last 5 retries)
Timeout	30 seconds
Retry condition	HTTP status != 200, business code != 10000, or network error
Success criteria	HTTP 200 with business response {"code": 10000, "message": "Success"}

Callback Request

Method

• Method: POST
• Content-Type: application/json
• Encoding: UTF-8

Headers

Header	Type	Required	Description
Content-Type	string	Y	application/json
Timestamp	string	Y	Timestamp (milliseconds)
Nonce	string	Y	Random string (UUID without dashes)
Signature	string	Y	Signature generated with Veloraya private key, used to verify callback authenticity

Callback Parameters (body)

Parameter	Type	Required	Description
merchantId	string	Y	Merchant ID
orderId	string	Y	Platform order ID (auto-generated)
merchantOrderId	string	Y	Merchant order ID; in Independent CVU mode this equals the platform order ID
orderStatus	string	Y	Order status, see order status enum
amount	BigDecimal	Y	Order amount
payAmount	BigDecimal	Y	Actual paid amount
currency	string	Y	Currency code, fixed ARS
fee	BigDecimal	Y	Fee (calculated by VA_DIRECT product rate)
createDatetime	string	Y	Order create time (Argentina timezone UTC-3), format: yyyy-MM-dd HH:mm:ss
completionDatetime	string	N	Order completion time (Argentina timezone UTC-3), format: yyyy-MM-dd HH:mm:ss
notifyType	string	Y	Notification type, fixed VA_DIRECT, distinguishes from order-mode callback
payerCuit	string	Y	Payer's full CUIT (11 digits), core basis for merchant to credit user
payerAccount	string	N	Payer's transfer-out account (fromCBU); may be null in manual backfill scenarios
receiveAccount	string	N	Receiving account (toCBU, i.e. the bound CVU); may be null in manual backfill scenarios
bankTxnId	string	Y	Coelsa bank transaction ID, for bank-side transaction traceability
errorCode	string	N	Error code (on failure)
errorMsg	string	N	Error message (on failure)

Order status enum

Value	Description
SUCCESS	Success
FAILED	Failed

Callback Example

Inbound success callback (auto order creation)

{
  "merchantId": "206092",
  "orderId": "AU2102293964635131904",
  "merchantOrderId": "AU2102293964635131904",
  "orderStatus": "SUCCESS",
  "amount": 100.00,
  "payAmount": 100.00,
  "currency": "ARS",
  "fee": 2.00,
  "createDatetime": "2026-09-22 04:08:34",
  "completionDatetime": "2026-09-22 04:08:36",
  "notifyType": "VA_DIRECT",
  "payerCuit": "20234567890",
  "payerAccount": "0000003100000000000001",
  "receiveAccount": "0000003100000000000099",
  "bankTxnId": "COELSA1234567890",
  "errorCode": null,
  "errorMsg": null
}

Manual补单 callback (payerAccount/receiveAccount null)

{
  "merchantId": "206092",
  "orderId": "AU2102293964635131904",
  "merchantOrderId": "AU2102293964635131904",
  "orderStatus": "SUCCESS",
  "amount": 100.00,
  "payAmount": 100.00,
  "currency": "ARS",
  "fee": 2.00,
  "createDatetime": "2026-09-22 04:08:34",
  "completionDatetime": "2026-09-22 04:08:36",
  "notifyType": "VA_DIRECT",
  "payerCuit": "20234567890",
  "payerAccount": null,
  "receiveAccount": null,
  "bankTxnId": "COELSA1234567890",
  "errorCode": null,
  "errorMsg": null
}

Callback Response

Success response

The merchant must return HTTP 200 with business code 10000 to acknowledge:

{
  "code": 10000,
  "message": "Success"
}

Failure response

If processing fails, return an error message (the system will keep retrying):

{
  "code": 40001,
  "message": "Processing failed"
}

Note

Only returning {"code": 10000, "message": "Success"} stops the retry. Any other response (including non-200 HTTP status) triggers the retry mechanism.

Signature Verification

Verification steps

1. Extract signature: get the Signature header
2. Build verification content: timestamp={timestamp},nonce={nonce},body={bodyJson}
   • Note: the verification content does NOT include merchantId, only timestamp, nonce and body
3. Verify with Veloraya public key: verify the signature with the public key provided by Veloraya
4. Use the unified guide: reuse the "Callback Verification Guide" and Appendix B sample code in API Signature

Key notes

• Veloraya public key: provided by Veloraya, used to verify callback signatures
• Algorithm: SHA256withRSA
• Encoding: UTF-8 + Base64

Business Rules

1. No order needed: the merchant does not need to call Create Payin Order; users transfer directly to the exclusive CVU to trigger the inbound callback
2. Exclusive CVU binding: 1 CVU is exclusively bound to 1 merchant; 1 merchant can bind multiple CVUs; once bound it is permanent and cannot be reassigned or deactivated
3. Fee: calculated by the merchant's VA_DIRECT payin product rate formula (fixedFee + amount × rateFee/100, subject to minFee)
4. Timezone: createDatetime and completionDatetime are in Argentina local time (UTC-3, no daylight saving)
5. User crediting basis: the merchant credits its own user based on payerCuit (payer CUIT) + bankTxnId (bank transaction ID) from the callback
6. Mutually exclusive modes: Independent CVU mode and Order Mode are mutually exclusive and cannot coexist; the merchant must confirm which mode to use before onboarding. If both modes are needed, contact your account manager to open two merchants

Notes

• Callback URL configuration: the Independent CVU callback URL vaNotifyUrl must be filled in by operations in the merchant-admin Access Configuration page before go-live; it is independent from the payin callback URL payinNotifyUrl
• Signature verification: always verify callback signature legitimacy; use the unified callback verification logic per API Signature
• Idempotency: implement idempotency to avoid duplicate processing; dedupe by orderId; the same inbound may produce multiple callbacks due to re-push or retry
• Field compatibility: notifyType = VA_DIRECT identifies this as an Independent CVU callback; order-mode payin callbacks do not include notifyType, so you can distinguish the two callback types by this field
• Null field handling: in manual backfill scenarios payerAccount and receiveAccount may be null; the merchant should handle nulls gracefully and reconcile via payerCuit + bankTxnId
• Response format: must return {"code": 10000, "message": "Success"} to stop retries
• Logging: log all callback requests, responses and processing time