Introduction

Welcome! Here at The Next Funstation, our mission is to provide infrastructure that helps you connect with Funstation services like payment, report, and play the arcade game machine.

The Next Funstation API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Authentication

To successfully authenticate with The Next Funstation's APIs, you must authenticate your secret API key using Basic Auth provided by funstation administrators. For example if your API key is

745b4bc3e055c79886812766626e3ad5

Select Funstation Auth authentication. Input secret API key in username and leave the password empty

Basic Auth format
{{username}}:{{password}}

Following the format (with colon)
745b4bc3e055c79886812766626e3ad5:

Encode Funstation Auth format above into Base64 format

NzQ1YjRiYzNlMDU1Yzc5ODg2ODEyNzY2NjI2ZTNhZDU6

Include Base64 encoded value in HTTP(s) header

Authorization: Funstation NzQ1YjRiYzNlMDU1Yzc5ODg2ODEyNzY2NjI2ZTNhZDU6

Funstation API is organized around REST to make it cleaner and easier to understand. All our API responses return JSON. To let you explore our APIs, make sure that you have API keys provided by Funstation Administrator.

To authenticate your account, you have to include your secret API key in the request. Here are the steps to authenticate your account:

Obtain your secret API key from Funstation Administrator
Select Funstation AUTH authentication
Funstation AUTH format will be {{username}}:{{password}}
Input Secret API key as username and leave the password empty. Make sure to include : at the end
Encode the value above into Base64 format
Include the base64 encoded into Authorization header

All the API requests should be made over HTTPS instead of HTTP (all calls made over plain HTTP will fail). All requests made in the test environment will never hit the banking networks and will not cost you anything. Your API keys should be kept private so do not share your secret API keys.

Request QR

Each API request has an asssociated request identifier. You can find this value in the response headers, under Request-ID. You can use Request-ID to find logs in API Logs in Dashboard. Learn more about Searching API Logs using Request-ID in API Logs Docs.

If you need to contact us about a specific request, providing the Request ID will ensure the fastest possible resolution.

Versioning

Versioning Example

curl https://api.xendit.co/ewallets -X POST \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   -H X-API-VERSION='2020-02-01' \
   -d external_id='ovo-ewallet' \
   -d amount=1000 \
   -d phone='08123123123'\
   -d ewallet_type='OVO'

Xendit evolves APIs continuously to grow together with you. We always strive to make backward-compatible changes. When we introduce backward-incompatible changes, we release a new dated version to avoid breaking your code and you can upgrade to newer versions whenever you are ready.

To see what version you're running and upgrade to the latest one, visit your Dashboard. To test a specific API version, you can override your API version by attaching API-Version header in API requests

Header	Description
API-Version optional	`string` Attach this parameter in the request to specify which API version you are going to request Format: `YYYY-MM-DD`. Example: `2020-02-01` Default value will follow your account API version settings

Backward Compatibility

We consider the following changes to be backward compatible:

Adding new API resources
Adding new optional request parameters to existing API methods
Adding new properties to existing API responses
Changing the order of properties in existing API responses
Changing the length or format of any object IDs
Adding new error codes
Adding new webhook event types
Adding new properties to webhook payloads

Migration Guide

The following guide will help you to migrate from your current version to latest version safely

Test new APis using explicit API-Version header in Test mode. Make sure you have handled new request,response, errors, and callback data correctly. Test scenarios can be found in Test Scenarios section
When everything is working as expected in Test mode, you can switch your Test mode API version in Dashboard. This switches the version used by API calls that don't have the API-Version header and also switches the version to render objects sent to your callback URLs
Repeat #1 and #2 respectively in Live mode
When faced with any disruption during migration process, you can always switch back to previous versions

Changelog

Version Date	API	Resources Path	Changelog
2020-02-21	eWallets	`/ewallets`	Create OVO Payment will be processed asynchronously and callback will be sent after process has been completed
2019-05-01	Credit Cards	`/credit_card_charges/refunds`	Create Refund will be processed synchronously

Rate Limit

API Rate Limit is a feature that limits the number of requests that a user or account can make to an API within a specific time period. This is often used to prevent excessive or abusive usage of an API, and to ensure that all users have fair access to the resources provided by the API.

Xendit uses the Sliding Window algorithm to implement API Rate Limit. This algorithm divides a specific time period (such as an hour or a day) into smaller windows, and tracks the number of requests made within each window. For example, if the rate limit is 50 requests per second (RPS), and the window size is one minute, the algorithm will allow up to 3000 requests in each one-minute window.

In general, API Rate Limit is set 3000 requests per minute (RPM) per endpoint per account in Test mode. In Live mode, the rate limit is set to 6000 requests per minute (RPM) per endpoint per account. The Rate Limit value can be different per endpoint when stated otherwise in each API section in API Reference. We return the following headers in API response to let you check Rate Limit details:

Response Header	Example Value	Description
Rate-Limit-Limit	6000	Containing the requests quota in the time window
Rate-Limit-Remaining	5839	Containing the remaining requests quota in the current window
Rate-Limit-Reset	58.379	Containing the time remaining in the current window, specified in seconds

Additionally, the rate limit of each unique IP address of the calling client can make a maximum of 18,000 requests per minute.

If you exceed the rate limit for an endpoint, you will receive an HTTP status code of 429 (Too Many Requests) with the error code RATE_LIMIT_EXCEEDED. It is important to handle this error and throttle your requests until the rate limit quota replenishes.

Here are some best practices for handling API Rate Limit gracefully as a client:

Implement rate limiting in your application: As a client, it is important to implement rate limiting in your own application to ensure that you do not exceed the API's rate limits. This can be done by tracking the number of requests made and the time at which they were made, and comparing this to the API's rate limit policies.
Handle rate limit errors: When you receive an HTTP status code of 429 (Too Many Requests) with the error code RATE_LIMIT_EXCEEDED, it is important to handle this error gracefully in your application. One way to do this is to retry the request after a certain amount of time has passed, to give the rate limit quota a chance to replenish.
Use exponential backoff: When retrying a request after a rate limit error, it can be helpful to use exponential backoff. This means that you should increase the amount of time you wait between retries by a factor of two (or some other multiplier) each time you receive a rate limit error. For example, you might retry the request after 1 second, then 2 seconds, then 4 seconds, and so on. This helps to reduce the risk of overwhelming the API with too many retries in a short period of time.
Use caching: Caching the results of API requests can help to reduce the number of requests made to the API, and can also improve the performance of your application. By storing the results of API requests locally and reusing them until they become stale, you can reduce the need to make frequent requests to the API.

By following these best practices, you can help to ensure that your application handles rate limits gracefully and provides a reliable and consistent experience for your users.

We may reduce limits to prevent abuse, or increase limits to enable high-traffic applications. To increase the rate limit for your account, you can contact us 4 weeks in advance via email [email protected] by providing your Business ID. We will review your request and may be able to increase the limit based on the needs of your application and the overall usage of the API.

Overall, it is important to carefully manage your API usage to ensure that you do not exceed the rate limits and disrupt the service for other users. By implementing proper rate limiting and error handling in your application, you can ensure that your users have a reliable and consistent experience when accessing the API.

Errors

Your Xendit integration might have to deal with errors at some point when making API requests to Xendit. These errors fall into a few major categories:

Content errors occur because the content in the API request was invalid in some way. They return an HTTP response with a 4xx error code. For example, the API servers might return a 401 if an invalid API key was provided, or a 400 if a required parameter was missing
Network errors occur as a result of intermittent communication problems between client and server. They return low-level errors, like socket or timeout exceptions. For example, a client might time out while trying to read from Xendit's servers, or an API response might never be received because a connection terminates prematurely. Note that a network errors wouldn't necessarily have otherwise been a successful request --- it can also be another type of error that's been cloaked by an intermittent problem
Server errors occur because of a problem on Xendit's servers. Server errors return an HTTP response with a 5xx error code. Xendit works to make these errors as rare as posslble, but integrations should be able to handle them when they do arise

The right approach and idempotency semantics to use for handling errors depend on the type of error being handled.

HTTP Status Code

Xendit uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc). Codes in the 5xx range indicate an error with Xendit's servers (these are rare).

Status Code	Description
200 - OK	Everything worked as expected
400 - Bad Request	The request was unacceptable, often due to missing a required parameter
401 - Unauthorized	No valid API key provided
403 - Forbidden	The API key doesn't have permissions to perform the request
404 - Not Found	The requested resources doesn't exist
500 - Server Errors	Something went wrong on Xendit's end (These are rare)

Error Code

Below are some of most common errors across all our endpoints. Specific errors are located under each endpoint.

Error Code	Description
API_VALIDATION_ERROR	Invalid request errors arise when your request has invalid parameters
INVALID_API_KEY	No valid API key provided
REQUEST_FORBIDDEN_ERROR	The API key doesn't have permissions to perform the request
SERVER_ERROR	API errors cover any other type of problem (e.g. a temporary problem with Xendit's servers), and are extremely uncommon

Error Handling

Safely retry requests with idempotency

A key part of web API design is the idea of idempotency, defined as being able to apply the same operation multiple times without changing the result beyond the first try. Because a certain amount of intermittent failure is to be expected, clients need a way of reconciling failed requests with a server, and idempotency provides a mechanism for that.

The Xendit API guarantees the idempotency of GET requests, so it's always safe to retry them. Including an idempotency key makes POST and PATCH request idempotent, which prompts the API to do the bookkeeping required to prevent duplicate operations. For example, if a request to create disbursements does not respond due to network connection error, you can retry the request with the same idempotency key to guarantee that no more than one disbursement is created.

Idempotency keys are sent in the x-idempotency-key header, and you should use them for all POST requests to Xendit's API whenever supported. A few common strategies for generating idempotency keys are:

Use an algorithm that generates a token with good randomness, like UUID v4
Derive the key from a user-attached object like the ID of a shopping cart. This provides a relatively easy way to protect against double submissions

A response that's being replayed from the server because it had already executed previously can be identified by the error code DUPLICATE_TRANSACTION_ERROR

Content errors

Content errros are the result of the contents of an API request being invalid and return a 4xx error code. Integrations should correct the original request and try again. Depending of the type of user error, it may be possible to handle the problem programmatically.

For a POST operation using an idempotency key, as long as an API method began execution, Xendit's API servers will cache the results of the request regardless of what they were. A request that returns a 400 will send back the same 400 if followed by a new request with the same idempotency key. A fresh idempotency key should be generated when modifying the original request to get a successful result. The safest strategy where 4xx errors are concerned is to always generate a new idempotency key.

Network errors

Network errors are the result of connectivity problems between client and server and tend to manifest as low-level errors like socket or timeout exceptions.

This class of errors is where the value of idempotency keys and request retries is most obvious. When intermittent problems occur, clients are usually left in a state where they don't know whether or not the server received the request. To get a definitive answer, they should retry such requests with the same idempotency keys and the same parameters until they're able to receive a result from the server. Sending the same idempotency with different parameters will produce an error indicating that the new request didn't match the original.

Server errors

Server errors are the result of a server-side problem and return a 5xx error code. These errors are the most difficult to handle, so we try to ensure that they happen as infrequently as possible.

As with the errors, retrying them with the same idempotency key will usually produce the same result. The request can be retried with a new idempotency key, but we'd advice against it because it's possible for the original one to have produced side effects.

The result of a 500 request should be treated as indeterminate. The exact nature of any retroactive changes in the system depend heavily on the type of request. For example, if creating a disbursement returns a 500 error but we detect that the information has gone out to a payment network, we'll try to roll it forward and send callback after it has been completed. If not, we'll try to roll it back. However, ideal results under these circumstances are not guaranteed, and requests resulting in a 500 error may proeduce user-visible side effects.

Treat requests that return 500 errors as indeterminate as ideal results are not guaranteed

Integration that want to maximize robustness must configure callback handlers that are capable of receiving events that have never been seen in an API response.

Webhook

Xendit uses webhook to notify your application any time an event happens on your account. Set up webhook for events that Xendit doesn't already notify you of, like when a disbursement has been completed, a Virtual Account has been created and paid, or your invoice has expired.

Setup

You need to provide an endpoint in your system to receive webhook from us. The webhook notification will be sent over POST request to your webhook URL that you have set. Setup your webhook URL in webhook settings. You can use a tool like ngrok to make your endpoint available for receiving webhook during testing.

Delivery Attempts and Retries

Understand how to view delivery attempts and retry logic when webhook events aren't acknowledged

View events

When viewing information about a specific event through the Dashboard's Webhook tab, you can check how many times Xendit attempted to send an event to the endpoint. This shows the latest response from your endpoint, a list of all attempted webhooks, and the respective HTTP status codes Xendit received.

Retry logic

Xendit attempts to deliver your webhook six times with exponential backoff between each interval and will stop retrying until we have received response from your server or there is still no response yet

Retry Number	Interval (relative to last retry)	Interval (relative to original attempt)
1	15m	15m
2	45m	1h
3	2h	3h
4	3h	6h
5	6h	12h
6	12h	24h

Receive webhook statistics via email

You can also receive summary of your webhook statistics (number of success and failed webhook) via email every 6 hours. You can enable this feature in Email Recipient settings

Event Handling

Handling webhook events correctly is crucial to making sure your integration's business logic works as expected

Acknowledge events immediately

If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before Xendit sees its complete execution. Ideally, your webhook handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that event.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events. We provide webhook-id as a unique identifier in the header parameter of every webhook to help you to implement idempotency. Learn about idempotency.

Order of events

Xendit does not guarantee delivery of events in the order in which they are generated. Your endpoint should not expect delivery of these events in this order and should handle this accordingly. You can also use the API to fetch any missing objects.

Security

Keeping your endpoints secure is critical to protecting your customers' information. Xendit provides several ways for you to verify events are coming from Xendit in a secure manner.

Receive events with an HTTPS server

If you use an HTTPS URL for your webhook endpoint, Xendit will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.

Verify events are sent from Xendit

Xendit can optionally sign the webhook events it sends to your endpoints. We do so by including a token in each event's x-callback-token header. This allows you to verify that the events were sent by Xendit, not by a third party.

Header Parameter	Description
x-callback-token	`string` Your Xendit unique webhook token to verify the origin of the webhook

Before you can verify tokens, you need to retrieve your webhook token from Dashboard's Webhook settings. Each secret is unique to each environments.

Balances

Get Balance

Endpoint: Get Balance

GET https://api.xendit.co/balance?account_type={account_type}

Balance is like your wallet since it will tell you how much money is available to you on Xendit. You can retrieve it to see the current balance on your Xendit cash account. Your balance is debited on any money out transaction, e.g. when performing disbursements or Xendit fees are charged. Your balance is credited when money comes into your account, e.g. invoices are paid or you deposit funds.

Request Parameters

Use API key permission Balance Read to perform this request

Example Get Balance Request

curl https://api.xendit.co/balance -X GET \
-u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:

<?php

  use Xendit\Xendit;
  require 'vendor/autoload.php';

  Xendit::setApiKey('xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=='); // this is Xendit API key example, you can go to Setting > API Key to get your API Key

  $getBalance = \Xendit\Balance::getBalance('CASH');
  var_dump($getBalance);

?>

const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });

const { Balance } = x;
const balanceSpecificOptions = {};
const b = new Balance(balanceSpecificOptions);

const resp = await b.getBalance()
console.log(resp);

Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
try {
  Balance balance = Balance.get();
} catch (XenditException e) {
  e.printStackTrace();
}

xendit.Opt.SecretKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="

data := balance.GetParams{
  AccountType: "CASH",
}

resp, err := balance.Get(&data)
if err != nil {
  log.Fatal(err)
}

fmt.Printf("balance: %+v\n", resp)

from xendit import Xendit, BalanceAccountType

api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
xendit_instance = Xendit(api_key=api_key)
Balance = xendit_instance.Balance

balance = Balance.get(
    account_type=BalanceAccountType.CASH,
)

print(balance)

string apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";

XenditClient xendit = new XenditClient(apiKey);
BalanceClient balance = xendit.Balance;

BalanceResponse holdingBalance = await balance.Get(BalanceAccountType.Holding);

Get Balance allows you to retrieve the balance of your cash and pending balance. Some use cases include: deciding when you may need to withdraw funds, and determining if you have funds to disburse

Header Parameter	Type	Description
for-user-id optional	`string`	The sub-account user-id that you want to make this transaction for. This header is only used if you have access to xenPlatform. See xenPlatform for more information

Query Parameter	Type	Description
account_type optional default: `CASH`	`string`	The selected balance type available values: `CASH`, `HOLDING`, `TAX`
currency optional	`string`	Currency filter for customers with multi currency accounts type. This field is only optional if you have only 1 currency. If you have more than 1 currency, please specify your desired currency. sample values: `IDR`, `PHP`, `USD`

Response Parameters

Example Get Balance Response

{
  "balance": 1241231
}

Parameter	Description
balance	The balance remaining in your cash account