Auth & Capture

Merchant Workflow

To initiate the payment in this scenario, the merchant needs to complete the following steps:

Completed account linking request and store returned access token
Optional: to retrieve user information or coin redemption using access token
Initiate an auth request with an amount
At a later time, initiate a capture request

Customer uses their linked ShopeePay account as the payment method to place the order, and the merchant calls ShopeePay to hold the amount.
The merchant calls ShopeePay to capture the final payment amount, based on the previous auth request.
If the order was later cancelled, the merchant calls ShopeePay to release the held amount.
ShopeePay will send an asynchronous message via Notify Transaction Status endpoint to inform merchants on the payment result.
Merchants can also call the Check Transaction Status endpoint to query the status of the transaction.
- If the Response Code is "Success", merchant can mark this transaction as successful.
- If the Response Code is "Failed", merchant can mark this transaction as failed.
- If the transaction is in a processing status, please retry the request at an incremental time range of every 5 seconds (e.g., 5 seconds, 10 seconds, 15 seconds, and so on) up to a maximum of 100 seconds. If there is no response after 100 seconds, please retry the request at an incremental time range of every 5 minutes up to 24 hours.
- If the transaction has no response, please retry the request at an incremental time range of every 5 seconds (e.g., 5 seconds, 10 seconds, 15 seconds, and so on) up to a maximum of 100 seconds. If there is no response after 100 seconds, please retry the request at an incremental time range of every 5 minutes up to 24 hours.
- If customer can show evidence of payment success on their payment app, merchant may choose to consider payment as successful and wait for reconciliation process on T+1 to settle discrepancies with ShopeePay, if any.

API Documentation

Create Auth

Use this endpoint to create an auth with an access token.

URL: "/v3/merchant-host/transaction/auth/create"

Request Parameters

request_idstring

Unique identifier for request.

auth_reference_idstring

Unique identifier of authorisation transaction generated by client.

Accepts up to 64 characters

merchant_ext_idstring

Unique identifier of merchant in client system.

store_ext_idstring

Unique identifier of store in client system.

access_tokenstring

The access token used to identify the user account.

amountint64

Amount used for the payment as integer, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point.

currencystring

Refers to the currency abbreviation for the transaction

return_urlstring

Indicates the URL of the Client's platform to redirect back to once payment verification on ShopeePay (if applicable) is done.

auth_expiry_timeuint32

Unix timestamp. The value represents when this auth transaction will expire. Maximum expiry time is 14 days from the time the request is received by ShopeePay.

Response Parameters

request_idstring

The same value as the request_id in the request.

errcodeint32

Error code to specify the error returned.

debug_msgstring

Debug message to provide more information.

redirect_urlstring

The URL for the Client''s frontend to redirect to for PIN verification, valid for 30 mins. Only applicable if PIN verification is needed.

transactionobject

Will return empty if no such transaction.

Sample API Response (with PIN verification)

Sample API Response (without PIN verification)

Response Code

Value	Description
-2	A server dropped the connection
-1	A server error occurred
0	Success
1	The Request Parameters is invalid or a mandatory parameter is empty
2	Permission denied, often due to invalid status
4	Not found, often due to merchant/store/user/transaction not found
5	Transaction is in processing status, use Check Transaction Status endpoint to query the updated status of the payment
9	Customer's account is banned
11	Duplicated request
14	Customer's account is deleted
24	Customer's account is frozen
27	Customer's account is not activated
42	Insufficient balance
43	Insufficient balance
50	The Request Parameters is invalid due to payload sent is not a valid JSON
105	Invalid auth code
140	Customer's wallet limit is reached
1001	Customer is not allowed to make the transaction
1100	ShopeePay internal payment module error
1101	ShopeePay internal payment module error
1102	Customer's SPL credit limit is reached
1103	Customer is required to link their bank account
1104	Ineligible payment channel
1106	Duplicated payment
1200	ShopeePay internal payment module error
1201	ShopeePay internal payment module error
1500	ShopeePay internal payment module error
1800	ShopeePay internal payment module error
1801	ShopeePay internal payment module error
1907	Ineligible payment channel
1908	Service is temporarily down for scheduled maintenance
300088	Customer is required to complete verification
300210	ShopeePay scam warning error message

Capture

Use this API to create a full or partial capture transaction using funds reserved from the corresponding auth transaction. Capture must be requested before the auth transaction expires. Only one capture, full or partial, will be accepted for each auth transaction.

URL: "/v3/merchant-host/transaction/auth/capture"

Request Parameters

request_idstringRequired

Unique identifier for request.

capture_reference_idstringRequired

Unique identifier of capture transaction generated by client.

Accepts up to 64 characters

merchant_ext_idstringRequired

Unique identifier of merchant in client system.

store_ext_idstringRequired

Unique identifier of store in client system.

amountint64Required

The amount to capture. Capture amount should be no greater than the original auth amount.

auth_reference_idstringRequired

The auth_reference_id of the auth transaction Client wants to capture.

use_coinbooleanOptional

Users may indicate their preference to use or not to use coins to offset their payment on the Client's platform. Use this field to pass the user's preference.

promo_idsstringOptional

Comma separated eligible promo_ids of 100 characters or less (up to 20), if any.

Response Parameters

request_idstring

The same value as the request_id in the request.

errcodeint32

Error code to specify the error returned.

debug_msgstring

Debug message to provide more information.

transactionobject

Will return empty if no such transaction.

Response Code

Value	Description
-2	A server dropped the connection
-1	A server error occurred
0	Success
1	The Request Parameters is invalid or a mandatory parameter is empty
2	Permission denied, often due to invalid status
4	Not found, often due to merchant/store/user/transaction not found
5	Transaction is in processing status, use Check Transaction Status endpoint to query the updated status of the payment
9	Customer's account is banned
11	Duplicated request
14	Customer's account is deleted
24	Customer's account is frozen
27	Customer's account is not activated
42	Insufficient balance
43	Insufficient balance
50	The Request Parameters is invalid due to payload sent is not a valid JSON
105	Invalid auth code
140	Customer's wallet limit is reached
1001	Customer is not allowed to make the transaction
1100	ShopeePay internal payment module error
1101	ShopeePay internal payment module error
1102	Customer's SPL credit limit is reached
1103	Customer is required to link their bank account
1104	Ineligible payment channel
1106	Duplicated payment
1200	ShopeePay internal payment module error
1201	ShopeePay internal payment module error
1500	ShopeePay internal payment module error
1800	ShopeePay internal payment module error
1801	ShopeePay internal payment module error
1907	Ineligible payment channel
1908	Service is temporarily down for scheduled maintenance
300088	Customer is required to complete verification
300210	ShopeePay scam warning error message

Reverse Auth

Use this API to reverse funds reserved previously using an auth request.

URL: "/v3/merchant-host/transaction/auth/reverse"

Request Parameters

request_idstringRequired

Unique identifier for request.

reverse_auth_reference_idstringRequired

Unique identifier of authorisation reversal transaction generated by client.

Accepts up to 64 characters

merchant_ext_idstringRequired

Unique identifier of merchant in client system.

store_ext_idstringRequired

Unique identifier of store in client system.

auth_reference_idstringRequired

The reference_id of the auth transaction Client wants to reverse.

Response Parameters

request_idstring

The same value as the request_id in the request.

errcodeint32

Error code to specify the error returned.

debug_msgstring

Debug message to provide more information.

transactionobject

Will return empty if no such transaction

Response Code

Value	Description
-2	A server dropped the connection
-1	A server error occurred
0	Success
1	The Request Parameters is invalid or a mandatory parameter is empty
2	Permission denied, often due to invalid status
4	Not found, often due to merchant/store/user/transaction not found
5	Transaction is in processing status, use Check Transaction Status endpoint to query the updated status of the payment
9	Customer's account is banned
11	Duplicated request
14	Customer's account is deleted
24	Customer's account is frozen
27	Customer's account is not activated
42	Insufficient balance
43	Insufficient balance
50	The Request Parameters is invalid due to payload sent is not a valid JSON
105	Invalid auth code
140	Customer's wallet limit is reached
1001	Customer is not allowed to make the transaction
1100	ShopeePay internal payment module error
1101	ShopeePay internal payment module error
1102	Customer's SPL credit limit is reached
1103	Customer is required to link their bank account
1104	Ineligible payment channel
1106	Duplicated payment
1200	ShopeePay internal payment module error
1201	ShopeePay internal payment module error
1500	ShopeePay internal payment module error
1800	ShopeePay internal payment module error
1801	ShopeePay internal payment module error
1907	Ineligible payment channel
1908	Service is temporarily down for scheduled maintenance
300088	Customer is required to complete verification
300210	ShopeePay scam warning error message