Auth & Capture

Merchant Workflow

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

Completed account linking request and store returned access token
Initiate an authorization request to reserve the estimated amount
Initiate a capture request to collect the final payment amount

Note:

The amount reserved on step 2, but not captured on step 3 will be released back to the customer
Authorization and Capture is useful for merchants that want to reserve customer's fund and deduct either a full or partial amount later
- Ride Hailing, Hotel Booking

The following figure illustrates the workflow of accepting a payment in the Authorization and Capture payment scenario:

Merchant calls Create Authorization to reserve the estimated amount to be charged.
1. After successful fund reservation, merchant can inform the customer that they can successfully proceed to the next step (E.g: merchant inform the customer that their booking is successful)
Merchant calls Create Capture to collect the final payment amount.
1. Any amount reserved during Authorization, but not collected in final payment capture will be returned to the customer once capture is successful
Merchant can calls Reverse Authorization to release the fund reserved during Authorization, e.g. if user cancels the booking
ShopeePay will send an asynchronous message via Notify Transaction Status endpoint to inform merchants on the payment result.
Merchant can also call these endpoints to check the transaction status:

Endpoint	Type of Transactions
/auth/query	Auth Transaction
/auth/capture-query	Capture Transaction
/auth/void-query	Void Transaction

Create Authorization

Use this endpoint to create an authorization to reserve funds for subsequent capture
All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	63
Path	..../v1.0/auth/payment
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
partnerReferenceNo	String	M	Unique identifier of authorization tranaction generated by merchant Accepts up to 64 characters
merchantId	String	M	Unique identifier of merchant in merchant system. Accepts up to 64 characters.
amount	Object	M
value	String	M	Transaction amount Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Currency that is associated with the transaction amount Accepted values: IDR
title	String	M	Auth description. Accepts up to 256 characters.
additionalInfo	Object	M
accountToken	String	M	The `accountToken` used to represent the account binding between merchant’s platform and ShopeePay.
externalStoreId	String	M	Unique identifier of store in merchant system. Accepts up to 64 characters.
returnUrl	String	C	Indicates the URL of the merchant’s platform to redirect back to once payment verification on ShopeePay (if applicable) is done.
authExpiryTime	String	O	The value represents when this auth transaction will expire. Maximum expiry time is 14 days from the time the request is received by ShopeePay. If no value is passed, the expiry time of an auth is by default 24 hours from the time the request is received by ShopeePay. Using ISO 8601 timestamp format.

Sample API Request

REQUEST

{
  "partnerReferenceNo": "Auth-123",
  "merchantId": "Merchant123",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "title": "Order description",
  "additionalInfo": {
    "accountToken": "+Tgd0x95GGgt3kN7m1ItWDGqCTAVYysV",
    "externalStoreId": "Store123",
    "returnUrl": "https://testing.com",
    "authExpiryTime": "2022-07-21T07:00:00+07:00"
  }
}

Copy

Response Parameter

Field	Type	Mandatory	Description
responseCode	String	M	Error code to specify the error returned.
responseMessage	String	M	Debug message to provide more information.
referenceNo	String	C	Transaction identifier in ShopeePay system.
partnerReferenceNo	String	O	Unique identifier of authorization transaction generated by merchant.
amount	Object	O
value	String	C	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	C	Currency that is associated with the transaction amount. Accepted values: IDR
paidTime	String	M	Update time of the individual transaction. Using ISO-8601 timestamp format.
additionalInfo	Object	O
latestTransactionStatus	String	O	Refer to Transaction Status for specific transaction statuses
merchantId	String	O	Unique identifier of merchant in merchant system.
externalStoreId	String	O	Unique identifier of store in merchant system.
createTime	String	O	Create time of the individual transaction. Using ISO-8601 timestamp format.
userIdHash	String	O	Identifier for customer that made the payment.
transactionType	uint32	O	1000 Refer to Transaction Types for specific transaction types.
redirectUrl	String	C	The URL for the merchant’s frontend to redirect to for PIN verification, valid for 30 mins. Only applicable if PIN verification is needed.
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

Sample API Response when ShopeePay PIN is not required

RESPONSE

{
   "responseCode": "2006300",
   "responseMessage": "Successful",
   "referenceNo": "Payment-Auth-123",
   "partnerReferenceNo": "Auth-123",
   "amount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "paidTime": "2022-07-20T07:10:01+07:00",
   "additionalInfo": {
      "merchantId": "Merchant123",
      "externalStoreId": "Merchant123",
      "createTime": "2022-07-20T07:10:00+07:00",
      "transactionType": 1000,
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "latestTransactionStatus": "00",
      "paymentChannel": 1
   }
}

Copy

Sample API Response when ShopeePay PIN is required

RESPONSE

{
  "responseCode": "2006300",
  "responseMessage": "Successful",
  "additionalInfo": {
    "redirectUrl": "https://uat.shopee.co.id/s/browser/payment/auth/passcode-verify?mode=fullscreen&next=https%3A%2F%2Fuat.shopee.co.id%2Fs%2Fbrowser%2Fpayment%2Fauth%2Ftokenized PaymentResult%3Freturn_url%3Dhttps%253A%252F%252Fgoogle.com%26ticket%3DepuhRVG3km0GbWqbWvTJV1dHvdKS4zdT&return_url=https%3A%2F%2Fuat.shopee.co.id%2Fs%2Fbrowser%2Fpayment%2Fauth %2Ftokenized PaymentResult%3Fresult 30201%26return_url%3Dhttps %253A%252F%252Fgoogle.com%26ticket 3 DepuhRVG3km GbWqbWvTJV1dHvdKS4zdT&scenario=7cdccb66-cd7a-448f-a01f-b2ddd8970e53&source=TokenizedPayment&ticket-epuhRVG3 km0GbWqbWvTJV1dHvdKS4zdT"
  }
}

Copy

Response Code

Please refer to the following description for a general explanation of the responseCode returned during an API Response.

For a more detailed explanation, it is advisable to consult responseMessage. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the responseMessage to their operators or staffs to facilitate prompt identification and resolution of the issue.

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	63	00	2006300	Successful	Mark Auth Payment process to Pending. if response.additionalInfo.redirectUrl is not empty. Redirect customer to Shopeepay page Mark Auth Payment process to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request "Auth Query" periodically if didn't get final status
400	63	00	4006300	Bad Request	Mark Auth Payment process to Failed. Retry request with proper parameter
400	63	01	4006301	Invalid field format {fieldName} Invalid Field Format {orderReferenceId}. Exceed Maximum Character Length Invalid Field Format {promoIds}. Exceed Maximum Character Length Invalid Field Format {authExpiryTime} Invalid Field Format {metadata}. Exceed Maximum Characters Invalid Field Format {metadata}. Maximum JSON Key Exceeded Invalid Field Format {metadata}. Invalid JSON Key Name Invalid Field Format {metadata} Invalid Field Format {title}. Exceed Maximum Character Length Invalid Field Format {return_url} Invalid Field Format	Mark Auth Payment process to Failed. Retry request with proper parameter
400	63	02	4006302	Invalid Mandatory Field {partnerReferenceNo} Invalid Mandatory Field {merchantId} Invalid Mandatory Field {externalStoreId} Invalid Mandatory Field {accountToken} Invalid Mandatory Field {value} Invalid Mandatory Field {currency} Invalid Mandatory Field {returnUrl} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid Mandatory Field {partnerReferenceNo}. Exceed Maximum 64 Characters Invalid Mandatory Field {returnUrl}. Exceed Maximum Character Length Invalid Mandatory Field {title} Invalid Mandatory Field + {error message}	Mark Auth Payment process to Failed. Retry request with proper parameter
401	63	00	4016300	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark Auth Payment process to Failed. Retry request with proper parameter
401	63	01	4016301	Invalid Token	Mark Auth Payment process to Failed. Retry request with proper parameter
403	63	01	4036301	Feature Not Allowed Feature Not Allowed. Selected Payment Channel Is Disabled For Merchant	Mark Auth Payment process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	63	02	4036302	Exceeds Transaction Amount Limit	Mark Auth Payment process to Failed. Adjust request amount
403	63	03	4036303	Suspected Fraud	Mark Auth Payment process to Failed. Retry request periodically or consult to Shopeepay
403	63	05	4036305	Do Not Honor. User Is Not Found Do Not Honor. User Is Not Activated Do Not Honor. User Is Banned Do Not Honor. User Is Locked Do Not Honor. User Is Deleted	Mark Auth Payment process to Failed. Retry request with proper parameter or can contact Shopeepay to check the user/account status
403	63	06	4036306	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark Auth Payment process to Failed. Retry request periodically or consult to Shopeepay
403	63	08	4036308	Invalid Merchant. Status Is Not Active	Mark Auth Payment process to Failed. Contact Shopeepay to check merchant/store status
403	63	14	4036314	Insufficient Funds	Mark Auth Payment process to Failed. Check source of fund
403	63	23	4036323	Account Limit Exceed	Mark Auth Payment process to Failed. Retry request periodically or consult to Shopeepay
404	63	08	4046308	Invalid Merchant Invalid Store. Status Is Not Active Invalid Merchant. Status Is Not Active	Mark Auth Payment process to Failed. Contact Shopeepay to check merchant/store status
404	63	11	4046311	Account Information Invalid	Mark Auth Payment process to Failed. Retry request with proper parameter
404	63	13	4046313	Invalid Amount. Non Positive Amount Is Not Allowed Invalid Amount Invalid Amount. Amount Does Not Support Cents	Mark Auth Payment process to Failed. Retry request with proper parameter
404	63	18	4046318	Inconsistent Request	Mark Auth Payment process to Failed. Retry request with proper parameter
409	63	00	4096300	Conflict	Mark Auth Payment process to Pending. Retry Retry request "Auth Query" periodically to get final status
500	63	00	5006300	General Error	Mark Auth Payment process to Pending. Retry Retry request "Auth Query" periodically to get final status
500	63	01	5006301	Internal Server Error	Mark Auth Payment process to Pending. Retry Retry request "Auth Query" periodically to get final status
504	63	00	5046300	Timeout	Mark Auth Payment process to Pending. Retry Retry request "Auth Query" periodically to get final status

Reverse Authorization

Use this endpoint to reverse funds previously reserved using an authorization request
All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	67
Path	.../v1.0/auth/void
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalReferenceNo	String	M	The auth transaction identifier in ShopeePay system.
originalPartnerReferenceNo	String	M	The auth transaction ID merchant wants to reverse.
partnerVoidNo	string	M	Unique identifier of authorisation reversal transaction generated by merchant. Accepts up to 64 characters.
merchantId	String	M	Unique identifier of merchant in merchant system. Accepts up to 64 characters.
additionalInfo	Object	M
externalStoreId	String	M	Unique identifier of store in merchant system. Accepts up to 64 characters.

Sample API Request

REQUEST

{
  "original ReferenceNo": "Payment-Auth-123",
  "originalPartnerReferenceNo": "Auth-123",
  "partnerVoidNo": "Void-123",
  "merchantId": "Merchant123",
  "additionalInfo": {
    "externalStoreId": "Store123"
  }
}

Copy

Response Parameter

Field	Type	Mandatory	Description
responseCode	String	M	Error code to specify the error returned.
responseMessage	String	M	Debug message to provide more information.
voidNo	String	C	Auth reversal transaction identifier in ShopeePay system. The value will be returned for successful reverse auth request.
partnerVoidNo	String	O	Unique identifier of auth reversal transaction generated by merchant.
voidAmount	Object	O
value	String	C	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	C	Currency that is associated with the transaction amount. Accepted values:IDR
voidTime	String	C	Update time of the individual void auth transaction.
additionalInfo	Object	O
merchantId	String	O	Unique identifier of merchant in merchant system
externalStoreId	String	O	Unique identifier of store in merchant system
createTime	String	O	Create time of the individual transaction. Using ISO-8601 timestamp format.
updateTime	String	O	Update time of the individual transaction. Using ISO-8601 timestamp format.
transactionType	uint32	O	1002 Refer to Transaction Types for specific transaction types
userIdHash	String	O	Identifier for customer that made the payment.
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

RESPONSE

{
  "responseCode": "2006700",
  "responseMessage": "Successful",
  "voidNo": "Shopee Pay-Void-123",
  "partnerVoidNo": "Void-123",
  "voidAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "additionalInfo": {
    "merchantId": "Merchant123",
    "externalStoreId": "Store123",
    "createTime": "2022-07-20T07:10:00+07:00",
    "updateTime": "2023-07-20T07:10:01+07:00",
    "transactionType": 1002,
    "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
    "paymentChannel": 1
  }
}

Copy

Response Code

Please refer to the following description for a general explanation of the responseCode returned during an API Response.

For a more detailed explanation, it is advisable to consult responseMessage. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the responseMessage to their operators or staffs to facilitate prompt identification and resolution of the issue.

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	67	00	2006700	Successful	Mark Auth Void process to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request "Auth Void Query" periodically if didn't get final status
400	67	00	4006700	Bad Request	Mark Auth Void process to Failed. Retry request with proper parameter
400	67	01	4006701	Invalid Field Format	Mark Auth Void process to Failed. Retry request with proper parameter
400	67	02	4006702	Invalid mandatory field {fieldName} Invalid Mandatory Field {merchantId} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid Mandatory Field {partnerVoidNo} Invalid Mandatory Field {originalPartnerReferenceNo} Invalid Mandatory Field {externalStoreId} Invalid Mandatory Field {partnerVoidNo}. Exceed Maximum 64 Characters Invalid Mandatory Field {originalPartnerReferenceNo}. Exceed Maximum 64 Characters Invalid Mandatory Field + {error message} Invalid Mandatory Field + {error message}	Mark Auth Void process to Failed. Retry request with proper parameter
401	67	00	4016700	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark Auth Void process to Failed. Retry request with proper parameter
401	67	01	4016701	Invalid Token	Mark Auth Void process to Failed. Retry request with proper parameter
403	67	00	4036700	Transaction Expired	Mark Auth Void process to Failed. Auth Payment already expired
403	67	01	4036701	Feature Not Allowed Feature Not Allowed. Selected Payment Channel Is Disabled For Merchant	Mark Auth Void process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	67	02	4036702	Exceeds Transaction Amount Limit	Mark Auth Void process to Failed. Retry request with proper parameter
403	67	06	4036706	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark Auth Void process to Failed. Retry request periodically or consult to Shopeepay
403	67	14	4036714	Insufficient Funds	Mark Auth Void process to Failed. Retry request periodically or consult to Shopeepay
403	67	15	4036715	Transaction Not Permitted. Auth Order Is Processing Transaction Not Permitted Transaction Not Permitted. Payment Is Already Completed	Mark Auth Void process to Failed. Retry request with proper parameter
403	67	23	4036723	Account Limit Exceed	Mark Auth Void process to Failed. Retry request with proper parameter
404	67	01	4046701	Transaction Not Found	Mark Auth Void process to Failed. Retry request with proper parameter
404	67	08	4046708	Invalid Merchant Invalid Merchant. Status Is Not Active Invalid Store. Status Is Not Active	Mark Auth Void process to Failed. Contact Shopeepay to check merchant/store status
404	67	18	4046718	Inconsistent Request	Mark Auth Void process to Failed. Retry request with proper parameter
409	67	00	4096700	Conflict	Mark Auth Void process to Pending. Retry request "Auth Void Query" periodically to get final status
409	67	01	4096701	Duplicate partnerVoidNo	Mark Auth Void process to Failed. Retry request with proper parameter
500	67	00	5006700	General Error	Mark Auth Void process to Pending. Retry request "Auth Void Query" periodically to get final status
500	67	01	5006701	Internal Server Error	Mark Auth Void process to Pending. Retry request "Auth Void Query" periodically to get final status
504	67	00	5046700	Timeout	Mark Auth Void process to Pending. Retry request "Auth Void Query" periodically to get final status

Check Authorization Status

Use this endpoint to query the status of an auth transaction.
Check Auth Transaction Status can’t be used for Auth transactions which are not made using ShopeePay Payment API.
- All API requests require a header. Refer to API Param Specification -> Transaction Request

Note:

While a 200xx00 response generally indicates a successful API call, the actual transaction might still be processing in the background. To confirm the latest status of your transaction, we strongly recommend referring to the latestTransctionStatus field in the API response. This will provide the most up-to-date information.

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	64
Path	.../v1.0/auth/query
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalPartnerReferenceNo	String	M	Unique identifier in merchant system.
merchantId	String	M	Unique identifier of merchant in merchant system.
externalStoreId	String	M	Unique identifier of store in merchant system.
additionalInfo	Object	M
value	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00

Sample API Request

REQUEST

{
  "originalPartnerReferenceNo": "Auth-123",
  "merchantId": "Merchant123",
  "externalStoreId": "Store123",
  "additionalInfo": {
    "value": "10000.00"
  }
}

Copy

Response Parameter

Field	Type	Mandatory	Description
responseCode	String	M	Error code to specify the error returned
responseMessage	String	M	Debug message to provide more information
originalReferenceNo	String	C	Transaction identifier in ShopeePay system. The value will be returned for successful auth.
originalPartnerReferenceNo	String	O	Unique identifier in merchant system.
latestTransactionStatus	String	M	Refer to Transaction Status for specific transaction statuses
paidTime	String	C	Update time of the individual transaction. The value will be returned for successful auth. Using ISO-8601 timestamp format.
amount	Object	O
value	String	C	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	C	Currency that is associated with the transaction amount. Accepted values: IDR
additionalInfo	Object	O
createTime	String	O	Create time of the individual transaction. Using ISO-8601 timestamp format.
productType	uint32	O	Indicates the payment method used. Refer to Product Types for the respective payment methods
transactionType	uint32	O	Refer to Transaction Types for specific transaction types
merchantId	String	O	Unique identifier of merchant in merchant system.
externalStoreId	String	O	Unique identifier of store in merchant system.
userIdHash	String	O	Unique identifier of the customer making the payment.
promoIdApplied	String	O	Comma separated eligible promoIds of 100 characters or less (up to 20), if any. These promoIds will be checked against promotional campaigns configured in ShopeePay to determine the valid reward amount the customer can receive for this transaction.
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

RESPONSE

{
  "responseCode": "2006300",
  "responseMessage": "Successful",
  "original ReferenceNo": "Payment-Auth-123",
  "originalPartnerReferenceNo": "Auth-123",
  "latestTransactionStatus": "00",
  "amount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "paidTime": "2022-07-20T07:10:01+07:00",
  "additionalInfo": {
    "createTime": "2022-07-20T07:10:00+07:00",
    "productType": 128,
    "transactionType": 1000,
    "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
    "merchantId": "Merchant123",
    "externalStoreId": "Store123",
    "paymentChannel": 1
  }
}

Copy

Response Codes

Please refer to the following description for a general explanation of the responseCode returned during an API Response.

For a more detailed explanation, it is advisable to consult responseMessage. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the responseMessage to their operators or staffs to facilitate prompt identification and resolution of the issue.

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	64	00	2006400	Successful	Mark Auth Payment to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request periodically when didn't get final status
400	64	00	4006400	Bad Request	Mark Auth Payment to Pending. Retry request with proper parameter
400	64	01	4006401	Invalid Field Format	Mark Auth Payment to Pending. Retry request with proper parameter
400	64	02	4006402	Invalid mandatory field {fieldName} Invalid field format {fieldName} Invalid mandatory field {partnerCaptureNo} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {merchantId/externalStoreId} Invalid Amount. Amount cannot contain cents Invalid Mandatory Field + {error message}	Mark Auth Payment to Pending. Retry request with proper parameter
401	64	00	4016400	Unauthorized invalid client key Unauthorized.{error message}	Mark Auth Payment to Pending. Retry request with proper parameter
401	64	01	4016401	Invalid Token	Mark Auth Payment to Pending. Retry request with proper parameter
404	64	01	4046401	Transaction not found	Mark Auth Payment to Pending. Retry request with proper parameter
404	64	08	4046408	Entity not found Invalid Store Invalid Merchant Invalid Merchant, Status Is Not Active Invalid Store, Status Is Not Active Invalid Merchant/Store, Status Is Not Active	Mark Auth Payment to Pending. Retry request periodically or consult to Shopeepay
404	64	13	4046413	Invalid Amount. Mismatch with original transaction Invalid amount. Mismatch with original transaction Invalid Amount. Non Positive Amount Is Not Allowed	Mark Auth Payment to Pending. Retry request with proper parameter
409	64	00	4096400	Conflict	Mark Auth Payment to Pending. Retry request periodically or consult to Shopeepay
500	64	00	5006400	General Error	Mark Auth Payment to Pending. Retry request periodically or consult to Shopeepay
500	64	01	5006401	Internal Server Error	Mark Auth Payment to Pending. Retry request periodically or consult to Shopeepay
504	64	00	5046400	Timeout	Mark Auth Payment to Pending. Retry request periodically or consult to Shopeepay

Create Capture

Use this endpoint to create a full or partial capture transaction using funds reserved from the corresponding authorization transaction.
Capture must be requested before the authorization transaction expires.
Only one partial capture will be accepted for each authorization transaction
- All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	65
Path	.../v1.0/auth/capture
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalReferenceNo	String	M	The auth transaction identifier in ShopeePay system.
originalPartnerReferenceNo	String	M	The auth transaction ID merchant wants to capture.
partnerCaptureNo	String	M	Unique identifier of capture transaction generated by merchant. Accepts up to 64 characters.
merchantId	String	M	Unique identifier of merchant in merchant system. Accepts up to 64 characters.
captureAmount	Object	M
value	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Currency that is associated with the transaction amount Accepted values: IDR
title	String	M	Capture description. Accepts up to 256 characters.
additionalInfo	Object	M
externalStoreId	String	M	Unique identifier of store in merchant system. Accepts up to 64 characters.
useCoin	Boolean	O	Use this field to indicate whether the customer prefers to use or not to use coins to offset their payment on the merchant’s platform. The default value is set to false. True: attempt to use coins False: do not use coins
promoIds	String	O	Comma separated eligible promoIds of 100 characters or less (up to 20), if any. These promoIds will be checked against promotional campaigns configured in ShopeePay to determine the valid reward amount the customer can receive for this transaction.
metadata	String	O	Additional information for the transaction. Additional information for the transaction. This field supports up to 3 fields and needs to be sent in this format {\”field1\”:\”{Data1}\”,\”field2\”:\”{Data2}\” ,\”field3\”:\”{Data3}\”}

Sample API Request

REQUEST

{
  "original ReferenceId": "Payment-Auth-123",
  "originalPartnerReferenceId": "Auth-123",
  "partnerCaptureNo": "Capture-123",
  "merchantId": "Merchant123",
  "captureAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "title": "Order description",
  "additionalInfo": {
    "externalStoreId": "Store123",
    "useCoin": false,
    "promoIds": "Promo1, Promo2",
    "metadata": "{\"field1\":\"Data1\",\"field2\":\"Data2\",\"field3\":\"Data3\"}"
  }
}

Copy

Response Parameter

Field	Type	Mandatory	Description
responseCode	String	M	Error code to specify the error returned.
responseMessage	String	M	Debug message to provide more information.
captureNo	String	C	Transaction identifier in ShopeePay system. The value will be returned for successful capture.
partnerCaptureNo	String	O	Unique identifier of capture transaction generated by client.
captureAmount	Object	M
value	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	M	Currency that is associated with the refund amount. Accepted values: IDR
captureTime	String	M	Update time of the individual transaction. Using ISO-8601 timestamp format.
additionalInfo	Object	O
merchantId	String	O	Unique identifier of merchant in merchant system
externalStoreId	String	O	Unique identifier of store in merchant system
latestCaptureStatus	String	O	Refer to Transaction Status for specific transaction statuses
createTime	String	O	Create time of the individual transaction.
transactionType	uint32	O	1001 Refer to Transaction Types for specific transaction types
userIdHash	String	O	Identifier for customer that made the payment
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

RESPONSE

{
   "responseCode": "2006500",
   "responseMessage": "Successful",
   "partnerCaptureNo": "Capture-123",
   "captureNo": "Payment-Capture-123",
   "captureAmount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "captureTime": "2022-07-20T07:10:05+07:00",
   "additionalInfo": {
      "merchantId": "Merchant123",
      "externalStoreId": "Store123",
      "createTime": "2022-07-20T07:10:04+07:00",
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813af222f6eab93b026ead62dc8d76",
      "transactionType": 1001,
      "latestCaptureStatus": "00",
      "paymentChannel": 1
   }
}

Copy

Response Code

Please refer to the following description for a general explanation of the responseCode returned during an API Response.

For a more detailed explanation, it is advisable to consult responseMessage. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the responseMessage to their operators or staffs to facilitate prompt identification and resolution of the issue.

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	65	00	2006500	Successful	Mark Auth Capture process to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request "Auth Capture Query" periodically if didn't get final status
400	65	00	4006500	Bad Request	Mark Auth Capture process to Failed. Retry request with proper parameter
400	65	01	4006501	Invalid Field Format {metadata}. Exceed Maximum Characters Invalid Field Format {metadata}. Maximum JSON Key Exceeded Invalid Field Format {metadata}. Invalid JSON Key Name Invalid Field Format {metadata}. Invalid Field Format {title}. Exceed Maximum Character Length Invalid Field Format	Mark Auth Capture process to Failed. Retry request with proper parameter
400	65	02	4006502	Invalid mandatory field {fieldName} Invalid field format {fieldName} Invalid field format {captureAmount.currency} Invalid Mandatory Field {merchantId} Invalid Mandatory Field {partnerCaptureNo} Invalid Mandatory Field {externalStoreId} Invalid Mandatory Field {originalPartnerReferenceNo} Invalid Mandatory Field {partnerCaptureNo}. Exceed Maximum 64 Character Invalid Mandatory Field {merchantId}. Exceed Maximum Character Length Invalid Mandatory Field {originalPartnerReferenceNo}. Exceed Maximum 64 Character Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid Mandatory Field {title} Invalid Mandatory Field + {error message}
401	65	00	4016500	Unauthorized. Invalid Client Key Unauthorized.{error message}	Mark Auth Capture process to Failed. Retry request with proper parameter
401	65	01	4016501	Invalid Token	Mark Auth Capture process to Failed. Retry request with proper parameter
403	65	00	4036500	Transaction Expired	Mark Auth Capture process to Failed. Auth Payment already expired
403	65	01	4036501	Feature Not Allowed Feature Not Allowed. Selected Payment Channel Is Disabled For Merchant	Mark Auth Capture process to Failed. Contact Shopeepay to check merchant/store supported product flow
403	65	02	4036502	Exceeds Transaction Amount Limit	Mark Auth Capture process to Failed. Retry request with proper parameter
403	65	05	4036505	Do not honor. Invalid status	Mark Auth Capture process to Failed. Retry request with proper parameter
403	65	06	4036506	Feature Not Allowed. Service Is Temporarily Down For Scheduled Maintenance	Mark Auth Capture process to Failed. Retry request periodically or consult to Shopeepay
403	65	14	4036514	Insufficient Funds	Mark Auth Capture process to Failed. Retry request periodically or consult to Shopeepay
403	65	15	4036515	Transaction Not Permitted. Auth Order Is Processing Transaction Not Permitted. Payment Is Already Completed	Mark Auth Capture process to Failed. Retry request with proper parameter
403	65	23	4036523	Account Limit Exceed	Mark Auth Capture process to Failed. Retry request with proper parameter
404	65	01	4046501	Transaction Not Found	Mark Auth Capture process to Failed. Retry request with proper parameter
404	65	08	4046508	Invalid Merchant Invalid Merchant. Status Is Not Active Invalid Store	Mark Auth Capture process to Failed. Contact Shopeepay to check merchant/store status
404	65	11	4046511	Account information invalid	Mark Auth Capture process to Failed. Retry request with proper parameter
404	65	13	4046513	Invalid Amount. Non Positive Amount Is Not Allowed Invalid Amount Invalid Amount. Amount Does Not Support Cents	Mark Auth Capture process to Failed. Retry request with proper parameter
404	65	18	4046518	Inconsistent Request	Mark Auth Capture process to Failed. Retry request with proper parameter
409	65	00	4096500	Conflict	Mark Auth Capture process to Pending. Retry request "Auth Capture Query" periodically to get final status
409	65	01	4096501	Duplicate partnerCaptureNo	Mark Auth Capture process to Failed. Retry request with proper parameter
500	65	00	5006500	General Error	Mark Auth Capture process to Pending. Retry request "Auth Capture Query" periodically to get final status
500	65	01	5006501	Internal Server Error	Mark Auth Capture process to Pending. Retry request "Auth Capture Query" periodically to get final status
504	65	00	5046500	Timeout	Mark Auth Capture process to Pending. Retry request "Auth Capture Query" periodically to get final status

Check Capture Transaction Status

Use this endpoint to query the status of capture transaction.
Check Capture Transaction Status API can’t be used for Capture transactions which are not made using ShopeePay Payment API.
- All API requests require a header. Refer to API Param Specification → Transaction Request

Note: While a 200xx00 response generally indicates a successful API call, the actual transaction might still be processing in the background. To confirm the latest status of your transaction, we strongly recommend referring to the latestCaptureStatus field in the API response. This will provide the most up-to-date information.

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	66
Path	.../v1.0/auth/capture-query
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalReferenceNo	String	M	Unique identifier in ShopeePay system.
partnerCaptureNo	String	M	Unique identifier in merchant system.
merchantId	String	M	Unique identifier of merchant in merchant system.
additionalInfo	Object	M
externalStoreId	String	M	Unique identifier of store in merchant system.
value	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00

Sample API Request

REQUEST

{
   "originalReferenceNo": "Capture-123",
   "partnerCaptureNo": "Payment-Capture-123",
   "merchantId": "Merchant123",
   "additionalInfo": {
      "externalStoreId": "Store123",
      "value": "10000.00"
   }
}

Copy

Response Parameter

Field	Type	Mandatory	Description
responseCode	String	M	Error code to specify the error returned
responseMessage	String	M	Debug message to provide more information
captureNo	String	C	Transaction identifier in ShopeePay system. The value will be returned for successful payment.
partnerCaptureNo	String	M	Unique identifier in merchant system.
latestCaptureStatus	String	M	Refer to Transaction Status for specific transaction statuses
captureTime	String	C	Update time of the individual transaction. The value will be returned for successful capture. Using ISO-8601 timestamp format.
captureAmount	Object	O
value	String	C	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency	String	C	Currency that is associated with the transaction amount. Accepted values: IDR
additionalInfo	Object	O
createTime	String	O	Create time of the individual transaction. Using ISO-8601 timestamp format.
productType	uint32	O	Indicates the payment method used. Refer to Product Types or the respective payment methods
transactionType	uint32	O	Refer to Transaction Types for specific transaction types.
merchantId	String	O	Unique identifier of merchant in merchant system.
externalStoreId	String	O	Unique identifier of store in merchant system.
userIdHash	String	O	Unique identifier of the customer making the payment.
promoIdApplied	String	O	Comma separated eligible promoIds of 100 characters or less (up to 20), if any. These promoIds will be checked against promotional campaigns configured in ShopeePay to determine the valid reward amount the customer can receive for this transaction.
paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

RESPONSE

{"responseCode": "2006600",
   "responseMessage": "Successful",
   "captureNo": "Capture-123",
   "partnerCaptureNo": "Payment-Capture-123",
   "captureTime": "2022-07-20T07:10:10+07:00",
   "latestCaptureStatus": "00",
   "captureAmount": {
      "value": "10000.00",
      "currency": "IDR"
   },
   "additionalInfo": {
      "createTime": "2022-07-20T07:10:09+07:00",
      "merchantId": "Merchant123",
      "externalStoreId": "Store123",
      "userIdHash": "15e455125fba426a4a2bb9145b3af2906813a7f222f6eab93b026ead62dc8d76",
      "productType": 128,
      "transactionType": 1001,
      "promoIdApplied": "Promo1, Promo2",
      "paymentChannel": 1
   }
}

Copy

Response Code

Please refer to the following description for a general explanation of the responseCode returned during an API Response.

For a more detailed explanation, it is advisable to consult responseMessage. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the responseMessage to their operators or staffs to facilitate prompt identification and resolution of the issue.

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	66	00	2006600	Successful	Mark Auth Capture to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request periodically when didn't get final status
400	66	01	4006601	Invalid field format {fieldName} Invalid Field Format	Mark Auth Capture to Pending. Retry request with proper parameter
400	66	02	4006602	Invalid mandatory field {originalReferenceNo} Invalid mandatory field {partnerCaptureNo} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {merchantId/externalStoreId} Invalid Amount. Amount cannot contain cents Invalid Mandatory Field + {error message}	Mark Auth Capture to Pending. Retry request with proper parameter
400	66	00	4006600	Bad Request	Mark Auth Capture to Pending. Retry request with proper parameter
401	66	00	4016600	Unauthorized invalid client key Unauthorized.{error message}	Mark Auth Capture to Pending. Retry request with proper parameter
401	66	01	4016601	Invalid Token	Mark Auth Capture to Pending. Retry request with proper parameter
404	66	01	4046601	Transaction not found	Mark Auth Capture to Pending. Retry request with proper parameter
404	66	08	4046608	Entity not found Invalid Store Invalid Merchant Invalid Merchant, Status Is Not Active Invalid Store, Status Is Not Active Invalid Merchant/Store, Status Is Not Active	Mark Auth Capture to Pending. Retry request periodically or consult to Shopeepay
404	66	13	4046613	Invalid Amount. Mismatch with original transaction Invalid amount. Mismatch with original transaction Invalid Amount. Non Positive Amount Is Not Allowed	Mark Auth Capture to Pending. Retry request with proper parameter
409	66	00	4096600	Conflict	Mark Auth Capture to Pending. Retry request periodically or consult to Shopeepay
500	66	00	5006600	General Error	Mark Auth Capture to Pending. Retry request periodically or consult to Shopeepay
500	66	01	5006601	Internal Server Error	Mark Auth Capture to Pending. Retry request periodically or consult to Shopeepay
504	66	00	5046600	Timeout	Mark Auth Capture to Pending. Retry request periodically or consult to Shopeepay

Check Void Auth-Transaction Status

Use this endpoint to query the status of an auth transaction that has been void.
Check Void Auth Transaction Status can’t be used for Auth transactions which are not made using ShopeePay Payment API.
- All API requests require a header. Refer to API Param Specification → Transaction Request

Specification

The following table is the specification of the API:

HTTP Method	POST
Service Code	68
Path	.../v1.0/auth/void-query
Version	v1.0

Request Parameter

Field	Type	Mandatory	Description
originalPartnerReferenceNo	String	M	Unique identifier of the transaction merchant would like to query.
originalReferenceNo	String	M	Unique identifier in ShopeePay system.
merchantId	String	M	Unique identifier of merchant in merchant system.
partnerVoidNo	String	M	Unique identifier of authorization reversal transaction generated by merchant.
additionalInfo	Object	M
amount	String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
transactionType	unit32	O	1002 Refer to Transaction Types for specific transaction types
externalStoreId	String	O	Unique identifier of store in merchant system Accepts up to 64 characters

Sample API Request

JS EXAMPLE

{
   "originalPartnerReferenceNo": "auth_void_integration_000044",
   "originalReferenceNo": "test_auth_void_integartion_00028",
   "merchantId": "openapi5_m8",
   "partnerVoidNo": "uat_auth_void_00024",
   "additionalInfo": {
      "externalStoreId": "openapi5_s8",
      "amount": "1.00",
      "transactionType": 1002
   }
}

Copy

Response Parameter

Field	Sub-Fields	Type	Mandatory	Description
responseCode		String	M	Error code to specify the error returned
responseMessage		String	M	Debug message to provide more information
voidAmount		object
value		String	M	Transaction amount. Sample: 10.000,00 will be placed with 10000.00
currency		String	M	Refers to the currency abbreviation for the transaction. IDR
voidTime		String	C	Update time of the individual void auth transaction.
latestVoidStatus		String	C	Refer to Transaction Status for specific transaction statuses
originalPartnerReferenceNo		String	O	Unique identifier of the transaction client would like to query.
originalReferenceNo		String	O	Unique identifier in ShopeePay system
additionalInfo		object	O
	transaction	object	O
	transactionType	uint32	O	Refer to Transaction Types for specific transaction types
	userIdHash	String	O	Unique identifier of the user making the payment.
	merchantId	String	O	Unique identifier of merchant in client system.
	externalStoreId	String	O	Unique identifier of store in client system.
	paymentChannel	int32	O	Indicates the source of fund used. Refer to Payment Channels for the respective source of fund.

Sample API Response

RESPONSE

{
   "responseCode": "2006800",
   "responseMessage": "Successful",
   "voidAmount": {
      "value": 1,
      "currency": "IDR"
   },
   "voidTime": "2024-07-02T15:28:36+07:00",
   "latestVoidStatus": "00",
   "additionalInfo": {
      "transaction": {
         "referenceId": "auth_void_integration_000044",
         "transactionSn": "135165152606180037",
         "transactionType": 1002,
         "userIdHash": "a8fbf03545686dacbe22beee16512f89d8403ce5a02d42512522724c1b09cfe1",
         "merchantExtId": "openapi5_m8",
         "storeExtId": "openapi5_s8",
         "paymentChannel": 1
      }
   }
}

Copy

Response Code

Please refer to the following description for a general explanation of the responseCode returned during an API Response.

For a more detailed explanation, it is advisable to consult responseMessage. This field provides additional information that can offer valuable insights for troubleshooting.

Merchants may choose to display the responseMessage to their operators or staffs to facilitate prompt identification and resolution of the issue.

HTTP code	Service Code	Sub-error Code	Response Code	Response Message	Partner Action
200	68	00	2006800	Successful	Mark Auth Void to corresponding status according to response.additionalInfo.latestTransactionStatus. Retry request periodically when didn't get final status
400	68	00	4006800	Bad Request	Mark Auth Void to Pending. Retry request with proper parameter
400	68	01	4006801	Invalid Field Format	Mark Auth Void to Pending. Retry request with proper parameter
400	68	02	4006802	Invalid mandatory field {fieldName} Invalid field format {fieldName} Invalid mandatory field {merchantId}. Exceed maximum character length Invalid mandatory field {externalStoreId}. Exceed maximum character length Invalid mandatory field {merchantId/externalStoreId} Invalid mandatory field {fieldName}. Exceed maximum character length Invalid Amount. Amount cannot contain cents Invalid Mandatory Field + {error message}	Mark Auth Void to Pending. Retry request with proper parameter
401	68	00	4016800	Unauthorized invalid client key Unauthorized.{error message}	Mark Auth Void to Pending. Retry request with proper parameter
401	68	01	4016801	Invalid Token	Mark Auth Void to Pending. Retry request with proper parameter
404	68	01	4046801	Transaction not found	Mark Auth Void to Pending. Retry request with proper parameter
404	68	08	4046808	Entity not found Invalid Store Invalid Merchant Invalid Merchant, Status Is Not Active Invalid Store, Status Is Not Active Invalid Merchant/Store, Status Is Not Active	Mark Auth Void to Pending. Retry request periodically or consult to Shopeepay
404	68	13	4046813	Invalid amount. Mismatch with original transaction Invalid amount. Mismatch with original transaction Invalid Amount. Non Positive Amount Is Not Allowed	Mark Auth Void to Pending. Retry request with proper parameter
409	68	00	4096800	Conflict	Mark Auth Void to Pending. Retry request periodically or consult to Shopeepay
500	68	00	5006800	General Error	Mark Auth Void to Pending. Retry request periodically or consult to Shopeepay
500	68	01	5006801	Internal Server Error	Mark Auth Void to Pending. Retry request periodically or consult to Shopeepay
504	68	00	5046800	Timeout	Mark Auth Void to Pending. Retry request periodically or consult to Shopeepay

Refund Payment

Use this endpoint to request a refund for a successful transaction. Refunds are subject to refund conditions.

HTTP Method	POST
Service Code	69
Path	.../v1.0/auth/refund
Version	v1.0

Refer to Refund Payment for the detail request and response parameters

Notify Transaction Status

Note: Merchant needs to confirm that both the payment amount and the originalPartnerReferenceNo correspond to the original /debit/payment-host-to-host request before considering the payment successful.

HTTP Method	POST
Service Code	56
Path	.../v1.0/debit/notify
Version	v1.0

Refer to Notify Transaction Status endpoint for the detail request body and response parameters.

Auth & Capture

Merchant Workflow

Create Authorization

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

Sample API Response when ShopeePay PIN is not required

RESPONSE

Sample API Response when ShopeePay PIN is required

RESPONSE

Response Code

Reverse Authorization

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Code

Check Authorization Status

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Codes

Create Capture

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Code

Check Capture Transaction Status

Specification

Request Parameter

Sample API Request

REQUEST

Response Parameter

Sample API Response

RESPONSE

Response Code

Check Void Auth-Transaction Status

Specification

Request Parameter

Sample API Request

JS EXAMPLE

Response Parameter

Sample API Response

RESPONSE

Response Code

Refund Payment

Notify Transaction Status

On this page