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

Field	Type	Description
request_id	string	Unique identifier for request.
auth_reference_id	string	Unique identifier of authorisation transaction generated by client.
merchant_ext_id	string	Unique identifier of merchant in client system.
store_ext_id	string	Unique identifier of store in client system.
access_token	string	The access token used to identify the user account.
amount	int64	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.
currency	string	Refers to the currency abbreviation for the transaction
return_url	string	Indicates the URL of the Client’s platform to redirect back to once payment verification on ShopeePay (if applicable) is done.
auth_expiry_time	uint32	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.

Sample API Request

REQUEST

{
    "request_id": "input-unique-request-id-here",
    "auth_reference_id": "ref-must-be-unique",
    "merchant_ext_id": "external-merchant",
    "store_ext_id":"external-store",
    "access_token": "uXjWuhPGepSOtntoC8kTK5er6DlbUiGeSJDt53",
    "amount": 100,
    "currency": "IDR"
}

Copy

Response Parameters

Field	Type	Description
request_id	string	The same value as the `request_id` in the request.
errcode	int32	Error code to specify the error returned.
debug_msg	string	Debug message to provide more information.
redirect_url	string	The URL for the Client’'s frontend to redirect to for PIN verification, valid for 30 mins. Only applicable if PIN verification is needed.
transaction	object	Will return empty if no such transaction.
reference_id	string	Unique identifier of auth transaction generated by client.
amount	int64	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.
status	uint32	Refer to Transaction Status for specific transaction statuses.
transaction_type	uint32	1000 (Refer to Transaction Types for specific transaction types).
transaction_sn	string	Transaction identifier in ShopeePay system.
create_time	uint32	Create time of the individual transaction.
update_time	uint32	Update time of the individual transaction.
user_id_hash	string	Identifier for user that made the payment.
merchant_ext_id	string	Unique identifier of merchant in Client system.
store_ext_id	string	Unique identifier of store in Client system.

Sample API Response (with PIN verification)

RESPONSE

{
    "request_id": "input-unique-request-id-here",
    "errcode": 0,
    "debug_msg": "success",
    "redirect_url": "http://shopeepay.com/user/auth-code/verify"
}

Copy

Sample API Response (without PIN verification)

RESPONSE

{
    "request_id": "input-unique-request-id-here",
    "errcode": 0,
    "debug_msg": "success",
    "transaction": {
        "reference_id": "input-payment-ref-id",
        "amount": 100,
        "create_time": 1716193693,
        "update_time": 1716193693,
        "transaction_sn": "4737856404311306",
        "status": 3,
        "transaction_type": 1000,
        "merchant_ext_id": "external-merchant",
        "store_ext_id": "external-store", 
        "user_id_hash": "697863f9295aeddcb3db598ecbc74c59a13335abf4d8c41b40e33b28a9d7d63c"
}

Copy

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

Field	Type	Mandatory	Description
request_id	string	Y	Unique identifier for request.
capture_reference_id	string	Y	Unique identifier of capture transaction generated by client.
merchant_ext_id	string	Y	Unique identifier of merchant in client system.
store_ext_id	string	Y	Unique identifier of store in client system.
amount	int64	Y	The amount to capture. Capture amount should be no greater than the original auth amount.
auth_reference_id	string	Y	The `auth_reference_id` of the auth transaction Client wants to capture.
use_coin	boolean	N	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_ids	string	N	Comma separated eligible promo_ids of 100 characters or less (up to 20), if any.

Sample API Request

REQUEST

{
    "request_id": "input-unique-request-id-here",
    "auth_reference_id": "input-auth-ref-id",
    "capture_reference_id": "input-capture-ref-id",
    "merchant_ext_id": "external-merchant",
    "store_ext_id": "external-store",
    "amount": 1000
}

Copy

Response Parameters

Field	Type	Description
request_id	string	The same value as the `request_id` in the request.
errcode	int32	Error code to specify the error returned.
debug_msg	string	Debug message to provide more information.
transaction	object	Will return empty if no such transaction.
reference_id	string	Unique identifier of capture transaction generated by client.
amount	int64	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.
status	uint32	Refer to Transaction Status for specific transaction statuses.
transaction_type	uint32	1000 (Refer to Transaction Types for specific transaction types).
transaction_sn	string	Transaction identifier in ShopeePay system.
create_time	uint32	Create time of the individual transaction.
update_time	uint32	Update time of the individual transaction.
user_id_hash	string	Identifier for user that made the payment.
merchant_ext_id	string	Unique identifier of merchant in Client system.
store_ext_id	string	Unique identifier of store in Client system.
promo_id_applied	string	`promo_id` applied to the payment transaction. This will be filled only if the user received a reward from a valid promotion with the promo_id specified.

Sample API Response

RESPONSE

{
    "request_id": "input-unique-request-id-here",
    "errcode": 0,
    "debug_msg": "success",
    "transaction": {
        "reference_id": "input-capture-ref-id",
        "amount": 100,
        "create_time": 1716193693,
        "update_time": 1716193693,
        "transaction_sn": "4737856404311306",
        "status": 3,
        "transaction_type": 1001,
        "merchant_ext_id": "external-merchant",
        "store_ext_id": "external-store", 
        "user_id_hash": "697863f9295aeddcb3db598ecbc74c59a13335abf4d8c41b40e33b28a9d7d63c"
}

Copy

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

Field	Type	Mandatory	Description
request_id	string	Y	Unique identifier for request.
reverse_auth_reference_id	string	Y	Unique identifier of authorisation reversal transaction generated by client.
merchant_ext_id	string	Y	Unique identifier of merchant in client system.
store_ext_id	string	Y	Unique identifier of store in client system.
auth_reference_id	string	Y	The `reference_id` of the auth transaction Client wants to reverse.

Sample API Request

REQUEST

{
    "request_id": "input-unique-request-id-here",
    "auth_reference_id": "input-auth-ref-id",
    "reverse_auth_reference_id": "input-reverse-auth-ref-id",
    "merchant_ext_id": "external-merchant",
    "store_ext_id": "external-store"
}

Copy

Response Parameters

Field	Type	Description
request_id	string	The same value as the `request_id` in the request.
errcode	int32	Error code to specify the error returned.
debug_msg	string	Debug message to provide more information.
transaction	object	Will return empty if no such transaction
reference_id	string	Unique identifier of auth reversal transaction generated by client.
amount	int64	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.
status	uint32	Refer to Transaction Status for specific transaction statuses.
transaction_type	uint32	1002 (Refer to Transaction Types for specific transaction types).
transaction_sn	string	Transaction identifier in ShopeePay system.
create_time	uint32	Create time of the individual transaction.
update_time	uint32	Update time of the individual transaction.
user_id_hash	string	Identifier for user that made the payment.
merchant_ext_id	string	Unique identifier of merchant in Client system.
store_ext_id	string	Unique identifier of store in Client system.

Sample API Response

RESPONSE

{
    "request_id": "input-unique-request-id-here",
    "errcode": 0,
    "debug_msg": "success",
    "transaction": {
        "reference_id": "input-reverse-auth-ref-id",
        "amount": 100,
        "create_time": 1716193693,
        "update_time": 1716193693,
        "transaction_sn": "4737856404311306",
        "status": 3,
        "transaction_type": 1002,
        "merchant_ext_id": "external-merchant",
        "store_ext_id": "external-store", 
        "user_id_hash": "697863f9295aeddcb3db598ecbc74c59a13335abf4d8c41b40e33b28a9d7d63c"
}

Copy

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

Auth & Capture

Merchant Workflow

API Documentation

Create Auth

Request Parameters

Sample API Request

REQUEST

Response Parameters

Sample API Response (with PIN verification)

RESPONSE

Sample API Response (without PIN verification)

RESPONSE

Response Code

Capture

Request Parameters

Sample API Request

REQUEST

Response Parameters

Sample API Response

RESPONSE

Response Code

Reverse Auth

Request Parameters

Sample API Request

REQUEST

Response Parameters

Sample API Response

RESPONSE

Response Code

On this page