Recurring billing

Integration guide

Integration guide

A. Processing flow

 

 

B. API Configuration

Header will build according to Integration rules for the APIs below.

 

1. Create first payment request

POST /v2/payments/recurring/request

 

Required parameters

Attribute Type Required Description
request_id

string (max 35 characters) does not contain special characters

Yes

Unique Merchant Request Code. Contains only letters, numbers and underscores.
request_type

string (max 35 characters) does not contain special characters

 Yes CIT
currency string Yes Currency : VND
amount number Yes

Amount to be paid

Min: 10.000 

Max: 200.000.000
method string Yes CREDIT_CARD
description string Yes Order information description
return_url sting Yes

A partner URL. This URL is used to redirect from 9Pay to the partner's purchase page after the customer makes a payment.
lang string No Language displayed on customer transaction screens (vi and en). Default is vi

  

Example request:               

{
  "request_id": "abc123_xyz789",
  "request_type": "CIT",
  "currency": "VND",
  "amount": 500000,
  "method": "card",
  "description": "Pay order #12345",
  "return_url": "https://merchant.vn/payment-return",
  "lang": "vi"
}

 

Return results

Attribute Type Required Description
request_id string Yes Same as original request code
order_code number Yes

9Pay transaction code
payment_url string Yes

URL to redirect customers to 9Pay's payment page
status number Yes

API transaction status
error_code number Yes

9pay list error code
failure_reason string Yes Error message corresponding to status = -1 
amount number Yes

Same as original amount
currency string Yes VND
submitted_at datetime Yes

Same as original amount

 

Sample returned results:

{
  "order_code": 274462355295201,
  "request_id": "cit00000005",
  "payment_url": "https://dev-payment.9pay.mobi/recurring/274462355295201",
  "status": 2,
  "failure_reason": null,
  "amount": 10000,
  "currency": "VND",
  "error_code": "000",
  "submitted_at": "2025-04-29T10:13:51.000000Z"
}

 

2. Processing transaction results

After the customer is redirected to the page 3ds_url to complete the authentication, the partner will receive the transaction results in the following 2 ways:

Return

Once the checkout flow is complete, the customer is redirected to return_url that the partner provided when generating the payment URL.

The partner uses this result to display a successful/failed transaction result message to the customer (Located in the query string when returning to the partner's link).

IPN- Instant Payment Notification

After the payment transaction is successful, 9Pay will send a POST request (x-www-form-data) to the address IPN_url of registered partners.

 

Return data

Attribute Type Required Description
result string Yes

Transaction result information
checksum string Yes

Checksum code generated using result and partner checksum key
version string Yes

IPN version

 

Value in result after decoding:

Attribute Type Required Description
order_code number Yes

9Pay transaction code
request_id string Yes

9Pay transaction code
amount number Yes

Same as initial payment
description string Yes

Order information description
request_type string Yes CIT
method string Yes CREDIT_CARD 
currency string Yes VND
created_at datetime Yes

Example: 1335939007 (UTC+0, length=10)
status number Yes

Transaction status
error_code number Yes

List error code
failure_reason string Yes

Reason for failed transaction
card_info string Yes

Payment information data
card_info.card_name string Yes

Cardholder name printed on card
card_info.card_brand string Yes

Card brand name
card_info.card_number string Yes Card number in the form 123456xxxxxx6789
card_info.token string Yes

Payment Token

 

3. Create payment request with token

POST /v2/payments/recurring/request

 

Required parameters

Attribute Type Required Description
request_id

string (max 35 characters) does not contain special characters

 Yes

Unique Merchant Request Code. Contains only letters, numbers and underscores.
request_type

string (max 35 characters) does not contain special characters

 Yes MIT
currency string Yes Currency : VND
amount number Yes

Amount to be paid

Min: 10.000 

Max: 200.000.000
method string Yes CREDIT_CARD
original_order_code number Yes

Order_code of the CIT transaction
card_token sting Yes

Payment Token

 

Example request:

{
  "request_id": "req_456def789",
  "request_type": "MIT",
  "currency": "VND",
  "amount": 250000,
  "method": "CREDIT_CARD",
  "original_order_code": 274462355295201,
  "card_token": "rnajkaf4952jf90f9effffqqqw"
}

 

Return results

Attribute Type Required Description
request_id string Yes

Same as original request code
order_code number Yes

9Pay transaction code
original_order_code number Yes

Same as original request
status number Yes

API status description
error_code number Yes

List error code description
failure_reason string Yes

Error message corresponding to status =-1 
amount number Yes

Same as original amount
currency string Yes VND
submitted_at datetime Yes

Payment request creation time (UTC +0)
auth_code string Yes

Authorization code

 

Sample returned results:

{
  "order_code": 277812340133889,
  "request_id": "MIT000000004",
  "original_order_code": 274293943437745,
  "auth_code": "831000",
  "status": 5,
  "failure_reason": null,
  "amount": 100000,
  "currency": "VND",
  "error_code": "000",
  "submitted_at": "2025-05-05T08:13:18.000000Z"
}

 

4. See more