ShopeePay Guide

DOKU has partnered with various e-money providers and one of them is ShopeePay to provide E-Money Payment. Learn more about how DOKU can help you integrate with ShopeePay here.

ShopeePay only compatible for Mobile Integration

ShopeePay integration is app-to-app redirection meaning that it will only available for mobile users

Integration steps

Here is the overview of how to integrate with ShopeePay:

Setup Return URL
Create order
Redirect to ShopeePay payment page to complete the payment
Acknowledge payment result

Direct API - ShopeePay Sequence Diagram

1. Setup `Return URL`

Based on the flow, the customers will redirected back to your site after completing the payment on ShopeePay application. Therefore, please setup the return URL:

Login to DOKU Back Office
Go to Configuration > E-Money
Click Configure button on ShopeePay channel
Input the Payment Return URL
Click Save button

2. Create order

To create an order, you will need to hit this API through your Backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/shopeepay-emoney/v2/order`
API endpoint (Production)	`https://api.doku.com/shopeepay-emoney/v2/order`

Here is the sample of request header to create an order:

Client-Id: MCH-0001-10791114622547
Request-Id: 24bb5232-3fe6-47a5-b0b0-d0fc3c6b5fdb
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is a sample of request body to create an order:

{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000,
        "callback_url": "https://merchant.com/return-url",
        "expired_time": 300
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`order.invoice_number`	`string`	Mandatory	Generated by merchant to identify the order and must unique per request Allowed chars: `alphabetic, numeric, special chars` Max length: `64`
`order.amount`	`number`	Mandatory	In IDR currency and without decimal Allowed chars: `numeric` Max length: `12`
`order.callback_url`	`string`	Mandatory	Merchant URL that will redirected to after the order completed
`order.expired_time`	`number`	Optional	Order expired time. Input value in seconds. 1. Max length: `4` 2. Max Value: `3600` 3. Recommended Value: `180 to 300` 4. Default Value: `300`

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	200
Result	SUCCESS

Client-Id: MCH-0001-10791114622547
Request-Id: 24bb5232-3fe6-47a5-b0b0-d0fc3c6b5fdb
Response-Timestamp: 2021-07-09T02:05:14Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "shopeepay_configuration": {
        "merchant_ext_id": "846609710695590",
        "store_ext_id": "99012984"
    },
    "shopeepay_payment": {
        "redirect_url_app" : "merchant://main?apprl=%2Frn%2FTRANSFER_PAGE%3Fnavigate_url%3Dhttps%253A%252F%252Fwallet.airpay.co.id%252Fwallet%252Fpay%253Ftoken%253D{paymentToken}",
        "redirect_url_http": "https://wallet.airpay.co.id/universal-link/wallet/pay?de ep_and_deferred=1&token=5a10f3bc-f555-4c92-8339-10421c09264a",
        "status": "SUCCESS"
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`order.invoice_number`	`string`	Mandatory	Same as the request
`order.amount`	`number`	Mandatory	Same as the request
`shopeepay_configuration.merchant_ext_id`	`string`	Optional	Merchant identifier by ShopeePay Max length: `15` Allowed chars: `alphabetic, numeric`
`shopeepay_configuration.store_ex_id`	`string`	Optional	Store identifier by ShopeePay Max length: `8` Allowed chars: `alphabetic, numeric`
`shopeepay_payment.redirect_url_http`	`string`	Conditional	Universal link to ShopeePay payment page
`shopeepay_payment.status`	`string`	Mandatory	Status of the create order request Possible value: `SUCCESS`, `FAILED`. If `FAILED`, initiate new order

2. Redirect to ShopeePay payment page to complete the payment

ShopeePay will display the order details in the Shopee App
Customer will check the payment amount and input ShopeePay PIN / Biometrics to complete the payment
ShopeePay returns the transaction result and the user is redirected to payment successful page. From the payment success page in ShopeePay, user can jump back to the Merchant's app using the return_url to view their order status.

3. Acknowledge payment result

DOKU will send HTTP Notification to your defined Notification URL. Learn how to handle the notification from DOKU:

Handling DOKU HTTP Notification

Additional features

We provide various addtional features to suited your needs. Learn more here.

Online Refund

To request a refund, you will need to hit this API through your backend:

API Request

Type	Value
HTTP Method	POST
API endpoint (Sandbox)	`https://api-sandbox.doku.com/shopeepay-emoney/v2/refund`
API endpoint (Production)	`https://api.doku.com/shopeepay-emoney/v2/refund`

Here is the sample of request header to generate payment URL:

Client-Id: MCH-0001-10791114622547
Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744
Request-Timestamp: 2020-08-12T09:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=

Request Header Explanation

Parameter	Description
Client-Id	Client ID retrieved from DOKU Back Office
Request-Id	Unique random string (max 128 characters) generated from merchant side to protect duplicate request
Request-Timestamp	Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z
Signature	Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to this section to generate the signature

Here is the sample request body to request a refund:

{
    "order": {
        "invoice_number": "MINV20201231468"
    },
    "shopeepay_payment": {
        "identifier": [
            {
                "name": "PAYMENT_REFERENCE_ID",
                "value": "REF-12345678"
            }
            {
                "name": "TRANSACTION_SN",
                "value": "000000012345678"
            }
        ]
    }
}

Request Body Explanation

Parameter	Type	Mandatory	Description
`order.invoice_number`	`string`	Mandatory	Invoice number of the transaction that being refunded
`shopeepay_payment.identifier`	`Array`	Mandatory	Get from payment notification response

API Response

After hitting the above API request, DOKU will give the response.

Type	Value
HTTP Status	200
Result	SUCCESS

Here is the sample response header:

Client-Id: MCH-0001-10791114622547
Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=

Response Header Explanation

Parameter	Description
Client-Id	Same as the request
Request-Id	Same as the request
Response-Timestamp	Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU
Signature	Signature generated by DOKU based on the response body

Here is the sample of response body:

{
    "service": {
        "id": "EMONEY”
    },
    "acquirer": {
        "id": "SHOPEE_PAY”
    },
    "channel": {
        "id": "EMONEY_SHOPEE_PAY”
    },
    “order”: {
        "invoice_number":"MINV20201231468",
        "amount":150000
    },
    "transaction": {
        "status": "REFUNDED”,
        "date": "2020-08-11T08:45:42Z",
        "original_request_id": "asdak1238912381"
    },
    "refund”: {
        "status": "SUCCESS",
        "date": "2020-08-11T08:45:42Z",
        "original_request_id": "asdak1238912381"
    },
    "additional_info": {
    },
    "shopeepay_configuration": {
        "merchant_ext_id": "846609710695590”,
        "store_ext_id”: "99012984”
    },
    "shopeepay_payment": {
        "identifier": [
            {
                "name": "PAYMENT_REFERENCE_ID”,
                "value": "REF-12345678”
            },{
                "name": "TRANSACTION_SN”,
                "value": "000000012345678”
            },{
                "name": "USER_ID_HASH”,
                "value": "dhfas0yd0ayf0sadf7nys0af0san7”
            },
        ],
        "transaction_status”: "3”,
        “transaction_message”: “Transaction successful”
    },
    "shopeepay_refund”: {
        "identifier": [
            {
                "name": "PAYMENT_REFERENCE_ID”,
                "value": "REF-12345678”
            },{
                "name": "TRANSACTION_SN”,
                "value": "000000012345678”
            },{
                "name": "USER_ID_HASH”,
                "value": "dhfas0yd0ayf0sadf7nys0af0san7”
            },
        ],
        "transaction_status”: "3”,
        “transaction_message”: “Transaction successful”
    }
}

Response Body Explanation

Parameter	Type	Mandatory	Description
`service.id`	`string`	Mandatory	Same as the request
`acquirer_id`	`string`	Mandatory	Same as the request
`channel.id`	`number`	Mandatory	Same as the request
`order.invoice_number`	`string`	Mandatory	Merchant invoice number, must unique per request per merchant
`order.amount`	`number`	Mandatory	Amount per request per merchant
`transaction.status`	`string`	Mandatory	Transaction status Possible value: `REFUNDED, SUCCESS, FAILED`
`transaction.date`	`string`	Mandatory	Time Stamp request on UTC time in ISO8601 format
`transaction.original_request_id`	`string`	Mandatory	Request Id from create order request
`refund.status`	`string`	Mandatory	Refund status Possible value: `SUCCESS, FAILED`
`refund.date`	`string`	Mandatory	Time Stamp request on UTC time in ISO8601 format
`refund.original_request_id`	`string`	Mandatory	Request Id from create order request
`additional_info`	`string`	Mandatory	Additional info
`shopeepay_configuration.merchant_ext_id`	`string`	Mandatory	Merchant identifier
`shopeepay_configuration.store_ext_id`	`string`	Mandatory	Merchant identifier
`shopeepay_payment.identifier`	`string`	Mandatory	Transaction data identifier
`shopeepay_payment.transaction_status`	`string`	Mandatory	Transaction data status
`shopeepay_payment.transaction_message`	`string`	Mandatory	Transaction message description
`shopeepay_refund.identifier`	`string`	Mandatory	Refund data identifier
`shopeepay_refund.transaction_status`	`string`	Mandatory	Refund data status
`shopeepay_refund.transaction_message`	`string`	Mandatory	Refund message description

Split Settlement

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.

Settlement

ShopeePay only compatible for Mobile Integration

Integration steps​

1. Setup Return URL​

2. Create order​

API Request​

API Response​

2. Redirect to ShopeePay payment page to complete the payment​

3. Acknowledge payment result​

Additional features​

Online Refund​

API Request​

API Response​

Split Settlement​

Integration steps

1. Setup `Return URL`

2. Create order

API Request

API Response

2. Redirect to ShopeePay payment page to complete the payment

3. Acknowledge payment result

Additional features

Online Refund

API Request

API Response

Split Settlement