How to Integrate

Set up your account

To use our Payouts APIs, register for a xendit account. After registration, you can start testing payouts on test mode.

Integration Checklist

Retrieve your API Key

We provide unique API keys for Development and Production environments. You can retrieve these from your Dashboard. Your API keys should be kept private, so do not share your secret API keys. To successfully authenticate with Xendit’s API, you must append a colon and Base 64 encode the API key. All API requests should be made over HTTPS instead of HTTP (all calls made over plain HTTP will fail).

Set callback URL

You should always set up your payout callback URL to use Payouts. Upon execution of the payout, we send you a callback with the updated status. If the payout was successfully executed, we send you a callback notifying you that the payout was completed. If the payout was not successfully executed, we send you a callback notifying you that payout has failed along with the appropriate failure code, to facilitate your decision on whether to send us another request to create payout or return the failure result to your customer.

To set this up, you can set up the callback URL in your dashboard settings. Nominate a callback URL for product Payouts V2.

Authentication

To ensure that the HTTP requests we receive are really from you, basic authentication using your API key must be applied to each request sent to us.

Your individual API key should be provided by your AM. This key will also be used by Xendit to identify which merchant is using the APIs. Make sure to store this key securely.

Xendit’s API Gateway uses basic access authentication. Use the format {{username}}:{{password}}; insert your API key as the username and leave the password blank. Then encode the string to Base64. The resulting string must be included in the Authorization HTTP header for every API call made.

Sample authentication string (in plain text) - take note of the colon:
xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==:

Sample base64 encoded string:
eG5kX2RldmVsb3BtZW50X1A0cURmT3NzME9DcGw4UnRLclJPSGphUVlOQ2s5ZE41bFNmaytSMWw5V2JlK3JTaUN3WjNqdz09Og==

Sample HTTP Authorization header:
Authorization: Basic eG5kX2RldmVsb3BtZW50X1A0cURmT3NzME9DcGw4UnRLclJPSGphUVlOQ2s5ZE41bFNmaytSMWw5V2JlK3JTaUN3WjNqdz09Og==

All the API requests should be made over HTTPS instead of HTTP (all calls made over plain HTTP will fail). Note that all requests made in the test environment will not be relayed to the banking networks and will thus not cost you anything.

Please allow us to emphasize: For the security of your funds, your API keys must be kept private, so do not share your secret API keys under any circumstance.

To help guide you through testing, the following is a complete guide on recommended steps and best practices.

Funds for Testing

After receiving sandbox credentials and setting up your callback URL, you can immediately start testing! Each sandbox account is pre-loaded with a test balance for use in simulating transactions:

If you need more funds for testing, feel free to reach out to your account manager to increase the balance of your test account.

Postman collection

To make it easier to get familiar with our APIs, we've published a Postman Collection so that you can try out all our APIs. Simply import this link into Postman: https://www.getpostman.com/collections/7a0843280dde5141d213

Tips & Best Practices

Steps to take before going live

Customers are encouraged to take all the following steps before going live to prevent losses and ensure that payouts are not delayed.

1. Set up your Callback URL to watch for and respond to payout events
2. Include an idempotency key in each payout for safe retries
3. Inform your recipient of the incoming transfer
4. Set up payout notifications to your recipient
5. Customize and test email receipts to ensure they look as you intend
6. Direct users to get support

Using Callback to track payouts

You should always set up your payout callback URL to use Payouts. Set up your callback URL on Dashboard > Settings > Developers > Callbacks and define a URL for v2/payouts.

Upon execution of the payout, we send you a callback with the updated status. If the payout was successfully executed, we send you a callback notifying you that the payouts succeeded. If the payout was not successfully executed, we send you a callback notifying you that payout has failed along with the appropriate failure code, to facilitate your decision on whether to send us another request to payout or return the failure result to your customer.

Use an idempotency key in every request for safe retries

We have built in idempotency into our Payouts API to enable you to retry the same request safely without risking a duplicate payout.

Be sure to include a unique ID (“idempotency key”) in each payout request. In the event of an ambiguous failure of a payout (i.e. due to an error in the process, you don’t know whether the payout has succeeded or not), you can retry the API call with the same idempotency key until the payout verifiably succeeds or fails. If our server receives a call which is a duplicate because the idempotency key already exists in our system, our system will ignore the duplicate request, ensuring the payout amount is only deducted once.

How recipients can identify payouts from you

We disburse funds on your behalf from our bank accounts. To help your recipient identify funds from you,

• Include your business name in the description of the disbursement - if the recipient's bank supports this field, the recipient will see this in their bank statement.
• For Indonesia, ask the recipient to look out for "PT SINAR DIGITAL TERDEPAN" or "PT SYAFTRACO" in their bank statement.
• For Philippines, ask the recipient to look out for “Xendit Philippines” or indications of interbank transfers Please note that the format and content of the disbursement description in their bank account inquiry or e-wallet statement may vary depending on the bank or e-wallet’s UI.

Set up payouts notifications to your recipient

Upon completion of payout, we send you an API callback with all transaction details, including the following:

• amount
• destination channel code
• destination account holder name
• description
• status of transaction You can customize your own payment confirmation UI with the callback information provided.

Customize and set up your email receipt

We provide an automatic email receipt which you can send to you and your recipient as a notification on proof of transfer. To do this, ensure to fill in the email_to, email_cc, and email_bcc fields (with maximum of 3 recipients per field) under the receipt_notfication parameter.

{
  "reference_id": "test-transaction-010121",
  "channel_code": "ID_MANDIRI",
  "amount": 10000,
  "description": "Test Txn 001",
  "currency": "IDR",
  "channel_properties" : {
    "account_holder_name": "Testing",
    "account number”: "1231231231231"
  },
    "receipt_notification": {
    "email_to": [
            "chen@example.co",
            "somebody@example.co"
        ],
     "email_cc": [
            "somebody@example.co",
            "somebody@example.co"
        ],
     "emai_bcc": [
            "somebody@example.co",
            "somebody@example.co"
        ]
    }
}

We display your logo and business details in each receipt. Be sure to test out the receipts by including your email address in the payoutrequest. You can then see what the email receipt looks like in your inbox.

Monitoring payouts

You can monitor the status of each payout via the Dashboard and via callbacks. We return you a callback when a payout has succeeded or failed. Alternatively, track the status of each payout via the Dashboard > Disbursements.

Direct your recipients to get support

As you control much of the payout experience, we recommend that your recipients reach out to you first with any questions.

If you had customized the email address of the sender of the receipt, your recipient will be able to respond to that email to reach your support team with any questions. To customize the Sender email address and footer message for payout receipts, please go to Dashboard > Settings > Disbursement Notifications.

However, your customer may have questions that only we can answer. To provide the most efficient support possible, we recommend that you contact us for these subjects:

• Missing payments or prolonged delay in payments (e.g., when the payout has been completed but the recipient has not received the payment after 1 working day)
• Payments received from “PT Sinar Digital Terdepan”, “PT Syaftraco” or “Xendit Philippines Inc” which were not expected by the recipient If any questions come up which you are unable to answer, reach out to us for help.

Last Updated on 2023-11-06