Subscription

Merchant Workflow

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

1. Completed account linking request and store returned access token
2. Initiate a payment request for Subscription when payment is due

1. Merchant calls Create Payment Order: Subscription endpoint to charge from the customer’s ShopeePay account.
2. ShopeePay will conduct a sequential attempt with each of the customer’s linked payment methods with ShopeePay, until the transaction is successful.
3. ShopeePay will sends an asynchronous message via Notify Transaction Status endpoint to inform merchants on the payment result.
4. Merchant can also call the Check Transaction Status endpoint to query the status of the transaction.
   • If the response code = "Success", the merchant can mark this transaction as successful.
   • If the response code = "Failed", the 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.

Create Payment Order: Subscription

Use this endpoint to create a direct payment with an access token.

• URL: "/v3/merchant-host/transaction/payment/direct"

Request Parameters

Sample API Request

REQUEST

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

Copy

Response Parameters

Sample API Response

RESPONSE

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

Copy

Response Code