# Payout Link

Handling payouts can be operationally complex, particularly when it involves collecting and managing bank account details from multiple recipients. To streamline this process, DOKU provides a feature called Payout Link. This feature allows merchants to send bonuses and commissions to their employees. 

With Payout Link, merchants are not required to manually collect or input beneficiary bank account information. Instead, DOKU automatically generates and sends a secure link to each beneficiary via email. The recipient can then submit their banking details directly through this link at their convenience.

### Integration Steps

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F3YsCHW1t8y06zve3MFdZ%2Fimage.png?alt=media&#x26;token=ee5f2584-7c57-4814-9555-69c276c43e56" alt=""><figcaption></figcaption></figure>

Here is the overview of how to integrate with Payout Link:

1. [Initiate Payout Link](#post-v1-payout-initiate)
2. [Check Payout Link Status](#post-v1-payout-status)

### Payout Link Status Mapping

Here is the possible value of Payout Link Status and the description:

| PENDING             | Payout link initiated successfully.                                                    |
| ------------------- | -------------------------------------------------------------------------------------- |
| EMAIL\_SENT         | Payout link email notification is sent.                                                |
| EMAIL\_LINK\_OPENED | Payout link opened through email.                                                      |
| PENDING\_PROCESS    | Payout link confirmation process has failed and will be retried.                       |
| CONFIRMED           | Payout link is confirmed, payment/remit request is sent to beneficiary and on process. |
| COMPLETED           | Payout link payment/remit request has been processed successfully.                     |
| FAILED              | Payout link payment/remit request has been retried 3 times and still failed.           |
| EXPIRED             | Payout link is expired because it's never opened.                                      |

***

### API Specification

| Type       | Value                          |
| ---------- | ------------------------------ |
| Sandbox    | <https://api-sandbox.doku.com> |
| Production | <https://api.doku.com>         |

## Payout Initiate

> Create a Payout Link transaction through API

```json
{"openapi":"3.0.0","info":{"title":"Kirim-Doku","version":"1.0.0"},"tags":[{"name":"API Payout","description":"API Payout for Kirim Doku, including Payout Initiate, Status, Confirmation"}],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{api-domain}"}],"paths":{"/v1/payout/initiate":{"post":{"tags":["API Payout"],"summary":"Payout Initiate","operationId":"payoutInitiate","description":"Create a Payout Link transaction through API","parameters":[{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/RequestTimeStampHeader"},{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/RequestIdHeader"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutInitiateRequest"}}},"description":"Payout Initiate request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutInitiateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutInitiateFailedParamResponse"}}}},"408":{"description":"Time out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutInitiateFailedTimeoutResponse"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutInitiateFailedInternalRSCoreResponse"}}}}}}}},"components":{"parameters":{"SignatureHeader":{"in":"header","name":"Signature","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},"RequestTimeStampHeader":{"in":"header","name":"Request-Timestamp","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssTZD format"},"ClientIdHeader":{"in":"header","name":"Client-Id","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},"RequestIdHeader":{"in":"header","name":"Request-Id","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"}},"schemas":{"PayoutInitiateRequest":{"type":"object","required":["amount","sender_name","receiver_name","receiver_phone_number","receiver_email","reference_id"],"properties":{"amount":{"$ref":"#/components/schemas/AmountRef"},"sender_name":{"$ref":"#/components/schemas/SenderRef"},"receiver_name":{"description":"Beneficiary / Receiver Name | min length: 1 | max length: 50","type":"string"},"receiver_phone_number":{"type":"string","description":"Beneficiary / Receiver Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 14"},"receiver_email":{"type":"string","description":"Beneficiary / Receiver Email | min length: 1 | max length: 50"},"reference_id":{"description":"Unique Reference number from merchant | min length: 1 | max length: 30","type":"string"},"description":{"description":"Decription min length: 1 | max length: 30","type":"string"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AmountRef":{"type":"number","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"SenderRef":{"description":"Sender Name | min length: 1 | max length: 50","type":"string"},"PayoutInitiateResponse":{"type":"object","required":["status","message","data"],"properties":{"status":{"type":"string","description":"status code"},"message":{"type":"string","description":"status message"},"timestamp":{"type":"string","format":"utc timestamp","description":"Doku's response time in yyyy-MM-ddTHH:mm:ssTZD format"},"data":{"type":"object","required":["transaction_id","reference_id"],"properties":{"reference_id":{"description":"Unique Reference number from merchant | min length: 1 | max length: 30","type":"string"},"transaction_id":{"description":"Unique Reference number from doku | min length: 1 | max length: 30","type":"string"},"status":{"type":"string","description":"Transaction status"},"amount":{"$ref":"#/components/schemas/AmountRef"},"sender_name":{"$ref":"#/components/schemas/SenderRef"},"receiver_name":{"description":"Beneficiary / Receiver Name | min length: 1 | max length: 50","type":"string"},"receiver_phone_number":{"type":"string","description":"Beneficiary / Receiver Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 14"},"receiver_email":{"type":"string","description":"Customer Email | min length: 1 | max length: 50"},"created_time":{"type":"string","format":"utc timestamp","description":"Doku's created time in yyyy-MM-ddTHH:mm:ssTZD format"},"modified_time":{"type":"string","format":"utc timestamp","description":"Doku's modified time in yyyy-MM-ddTHH:mm:ssTZD format"}}}}},"PayoutInitiateFailedParamResponse":{"type":"object","required":["status","message","data"],"properties":{"status":{"type":"string","description":"status code"},"message":{"type":"string","description":"status message"},"timestamp":{"type":"string","format":"utc timestamp","description":"Doku's response time in yyyy-MM-ddTHH:mm:ssTZD format"},"errors":{"type":"array","items":{"type":"object"}}}},"PayoutInitiateFailedTimeoutResponse":{"type":"object","required":["transactionId","referenceId","data"],"properties":{"status":{"type":"string","description":"status code"},"message":{"type":"string","description":"status message"},"timestamp":{"type":"string","format":"utc timestamp","description":"Doku's response time in yyyy-MM-ddTHH:mm:ssTZD format"},"data":{"type":"object","required":["reference_id"],"properties":{"reference_id":{"description":"Unique Reference number from merchant | min length: 1 | max length: 30","type":"string"}}}}},"PayoutInitiateFailedInternalRSCoreResponse":{"type":"object","required":["transactionId","referenceId","data"],"properties":{"status":{"type":"string","description":"status code"},"message":{"type":"string","description":"status message"},"timestamp":{"type":"string","format":"utc timestamp","description":"Doku's response time in yyyy-MM-ddTHH:mm:ssTZD format"},"data":{"type":"object","required":["reference_id"],"properties":{"reference_id":{"description":"Unique Reference number from merchant | min length: 1 | max length: 30","type":"string"}}}}}}}}
```

## Payout Status

> Check Payout Link current status through API

```json
{"openapi":"3.0.0","info":{"title":"Kirim-Doku","version":"1.0.0"},"tags":[{"name":"API Payout","description":"API Payout for Kirim Doku, including Payout Initiate, Status, Confirmation"}],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{api-domain}"}],"paths":{"/v1/payout/status":{"post":{"tags":["API Payout"],"summary":"Payout Status","operationId":"payoutStatus","description":"Check Payout Link current status through API","parameters":[{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/RequestTimeStampHeader"},{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/RequestIdHeader"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutStatusRequest"}}},"description":"Payout Check Status request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutStatusResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutStatusFailedResponse"}}}}}}}},"components":{"parameters":{"SignatureHeader":{"in":"header","name":"Signature","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},"RequestTimeStampHeader":{"in":"header","name":"Request-Timestamp","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssTZD format"},"ClientIdHeader":{"in":"header","name":"Client-Id","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},"RequestIdHeader":{"in":"header","name":"Request-Id","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"}},"schemas":{"PayoutStatusRequest":{"type":"object","required":["transaction_id"],"properties":{"transaction_id":{"description":"Must be the same as reference_id given in the payout initiate request | min length: 1 | max length: 30","type":"string"}}},"PayoutStatusResponse":{"type":"object","required":["status","message","data"],"properties":{"status":{"type":"string","description":"status code"},"message":{"type":"string","description":"status message"},"timestamp":{"type":"string","format":"utc timestamp","description":"Doku's response time in yyyy-MM-ddTHH:mm:ssTZD format"},"data":{"type":"object","required":["transaction_id","reference_id"],"properties":{"reference_id":{"description":"Unique Reference number from merchant | min length: 1 | max length: 30","type":"string"},"transaction_id":{"description":"Unique Reference number from doku | min length: 1 | max length: 30","type":"string"},"status":{"type":"string","description":"Transaction status"},"state":{"type":"string","description":"Transaction state. GENERATED / PROCES / DONE"},"amount":{"$ref":"#/components/schemas/AmountRef"},"sender_name":{"$ref":"#/components/schemas/SenderRef"},"receiver_name":{"description":"Beneficiary / Receiver Name | min length: 1 | max length: 50","type":"string"},"receiver_phone_number":{"type":"string","description":"Beneficiary / Receiver Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 14"},"receiver_email":{"type":"string","description":"Customer Email | min length: 1 | max length: 50"},"created_time":{"type":"string","format":"utc timestamp","description":"Doku's created time in yyyy-MM-ddTHH:mm:ssTZD format"},"modified_time":{"type":"string","format":"utc timestamp","description":"Doku's modified time in yyyy-MM-ddTHH:mm:ssTZD format"}}}}},"AmountRef":{"type":"number","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"SenderRef":{"description":"Sender Name | min length: 1 | max length: 50","type":"string"},"PayoutStatusFailedResponse":{"type":"object","required":["status","message","data"],"properties":{"status":{"type":"string","description":"status code"},"message":{"type":"string","description":"status message"},"data":{"type":"object","properties":{"transaction_id":{"description":"Unique Reference number from doku | min length: 1 | max length: 30","type":"string"}}}}}}}}
```