> For the complete documentation index, see [llms.txt](https://developers.doku.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.doku.com/accept-payments/direct-api/snap/integration-guide/e-wallet/shopeepay.md).

# ShopeePay

## Integration Steps

Overview of integration process with ShopeePay.

1. [Payment](#1.-payment)
2. [Payment Notification](#id-2.-payment-notification)
3. [Additional Feature](#id-3.-additional-feature)

***

### 1. Payment 

Payment process using ShopeePay doesn't require account binding. After customer creates an order and chooses ShopeePay as payment method on merchant's platform, merchant will hit this payment API to get redirect URLs to ShopeePay's platform for customer to complete the payment.

Source of Fund Options for ShopeePay Payment.

There are a few source of fund options that can be used for ShopeePay payments:

* ShopeePay Wallet Balance – This is the default source of fund for all ShopeePay payments.
* ShopeePayLater – This option requires prior approval from ShopeePay. DOKU can help facilitate the application process through our Sales and Business team when the channel is activated.
  * Note: To enable ShopeePayLater as an additional source of fund (alongside ShopeePay Wallet Balance), merchants are required to implement the API Refund feature.

**API Endpoint**

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

## POST /direct-debit/core/v2/debit/payment-host-to-host

> Request Payment

```json
{"openapi":"3.0.3","info":{"title":"Swagger Direct Debit SNAP SHOPEEPAY","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v2/debit/payment-host-to-host":{"post":{"summary":"Request Payment","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"X-DEVICE-ID","schema":{"type":"string"},"required":false,"description":"Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols"},{"in":"header","name":"X-IP-ADDRESS","schema":{"type":"string"},"description":"conditional. IP address of the end user (customer) using IPv4 format"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}}}}}},"components":{"schemas":{"PaymentRequest":{"type":"object","required":["partnerReferenceNo","amount","urlParams"],"properties":{"partnerReferenceNo":{"type":"string","description":"invoice number from partner | max: 64 | Mandatory "},"validUpTo":{"type":"string","description":"Expired time payment url | format: 2024-07-10T11:57:58+07:00 Maximum expiry date is 1 day/24 hours"},"pointOfInitiation":{"type":"string","description":"Point of initiation from partner | value: app/pc/mweb | max: 20"},"urlParams":{"type":"array","items":{"type":"object","required":["url","type","isDeepLink"],"properties":{"url":{"type":"string","description":"URL partner for redirect back from shopee | Format in HTTP link | max: 255 | Mandatory"},"type":{"type":"string","description":"Pay Return | Value should be always PAY_RETURN | Mandatory"},"isDeepLink":{"type":"string","description":"Is Merchant use deep link or not | value: Y/N | Mandatory"}}}},"amount":{"$ref":"#/components/schemas/AmountObject"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"Value should be always EMONEY_SHOPEE_PAY_SNAP | Mandatory"}}}}},"AmountObject":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"PaymentResponse":{"type":"object","required":["responseCode","responseMessage","webRedirectUrl"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-3.-e-wallet . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Message"},"webRedirectUrl":{"type":"string","description":"Redirect URL to Merchant's page/platform for customer to input OTP/PIN"},"referenceNo":{"type":"string","description":"Reference Number from Acquirer "},"partnerReferenceNo":{"type":"string","description":"Invoice Number from Partner"}}}}}}
```

{% openapi src="/files/xyUnrXWZRaMrmRd5e6gz" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-dd-shopee (4).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fo96nTx32wNxTNpIQgFof%2Fswagger-dd-shopee%20\(4\).yaml?alt=media\&token=26b264d8-d210-481d-8b7e-1b4fe0640d3a)
{% endopenapi %}

***

### 2. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL.` Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification.md).

***

### 3. Additional Feature

### **Online Refund**

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU.

**Refund Eligibility**

* To enable ShopeePayLater as an additional source of fund (alongside ShopeePay Wallet Balance), merchants are required to implement the API Refund feature.
* Refund can only be performed for transactions with successful payment status. Refund may be full or partial, provided that the total refunded amount does not exceed the original transaction amount. Refund requests must be submitted via API.
* The refund expiration period is set at 365 days, starting from the initial payment date.&#x20;
* For transactions paid using ShopeePay Wallet Balance, the refund amount must not cause the user’s wallet balance to exceed the maximum wallet balance limit (up to IDR 2,000,000 for non-verified users and up to IDR 20,000,000 for verified users). If the user’s wallet balance has reached its maximum limit at the time of refund, the refund request will still be accepted via API but will remain in pending/processing status on ShopeePay’s side. The refund will be automatically processed once the user’s wallet balance becomes available. In this scenario, merchants do not need to resubmit the refund request.
* For transactions paid using ShopeePayLater, refund is expected to be processed in real time under normal conditions. In some edge cases where real-time processing is not successful due to system issues, merchants may contact DOKU support for further assistance and investigation.

**API Endpoint**

<table><thead><tr><th width="181">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/6ihUnXg4J36w4vERWzWr" path="/direct-debit/core/v1/debit/refund" method="post" %}
[Swagger ShopeePay SNAP - Updated 110325 (1).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Ftjfh18lDa3vBAtA95A5i%2FSwagger%20ShopeePay%20SNAP%20-%20Updated%20110325%20\(1\).yaml?alt=media\&token=3827809f-c44a-4174-ba38-61f617545bdb)
{% endopenapi %}