On-Demand Debit API
Explore our On-Demand Debit API documentation and examples to integrate borderless into your application. Our On-Demand Debit documentation will provide you with all the required information to unlock custom collection capabilities for your operations.
Contents
Introduction
The borderless GraphQL API allows your business to debit customers’ bank accounts at any time streamlining your operations. This solution is built for small-businesses, enterprises, and dreamers around the world.Ā
With our On-Demand Debit API you can get paid from your clients at any time. The funds get debited from their bank account and are delivered straight to your bank account with $0 wire fees and currency conversion included. These docs will provide:Ā Ā
- Quick Start: Step by Step on how to get started
- Integration methods: Choose your integration method to unlock On-Demand Debits
- Guide & Resources: Follow our API guides for easy integration
Note: The borderless On-Demand Debit API takes about 1-4 days to implement. Integration time depends on your company needs, and development resources.
On-Demand Debit Experience
The payment experience is important to us that’s why we have built borderless to be flexible to your needs. We have built 2 debit experiences which can be used. Choosing an experience will impact your development time to integrate with our solution.Ā
- On-Demand Debit API – This method allows On-Demand Debits to be triggered via API, integrated with your solution and customized to your specific needs.
- PlansĀ – This requires no development work. This tool is needed to manage your On-Demand Debit plans regardless if use our API or not.Ā
On-Demand Flow Overview
The On-Demand Debit experience is a simple and easy to manage.
- Step 1: You create an On-Demand Direct Debit Plan using our Plans tab in your dashboard.
- Step 2: You enter the plan name, maximum amount that can be charged and description. All details will be displayed to the customer when they are invited.
- Step 3: Invite 1 or multiple clients via email or using their PayMe handles “@borderless” or include a link on your website or custom emails.Ā
- Step 4 (optional): The customer receives an invitation asking them to subscribe to the On-Demand Direct Debit Plan. If a link is used, this step is skipped.
- Step 5: The customer will log in to their borderless account and accept the details of the plan. If they don’t have a borderless account, they can create one in under 5 minutes.Ā
- Step 6: You get notified of their action and now can debit their bank account. You can use our dashboard or On-Demand Debit API to trigger debits at any time.
- Step 7: Once you trigger a debit, the customer gets notified and the payment is processed after 3 business days. The customer needs to be notified 3 days in advance. The funds then takes 2-3 business days after being processed to be reflected in your bank account. We recommend you debit a customer’s bank account a week beforehand.
On-Demand Debit Dashboard
The On-Demand Debit Dashboard is a simple UI system that allows you to create, manage and execute plans using our dashboard. To learn more about how to create and manage your plans, contact your account manager or our sales team here.
Getting Started
Ready to unlock global bank payouts? Our Mass Payout API guide will walk you through how you can pay multiple users around the world in seconds. The funds gets delivered straight to their bank account with $0 wire fees and better exchange rates than most banks or PayPal.
Step 1: Sign Up
Before using this guide, ensure you have a business account registered on our live environment for production use.
Step 2: Enable On-Demand Debits via API
Once you have an account registered, contact borderless support in order to enable the On-Demand Debit API for your account.
Upon enabling On-Demand Debits via API, borderless will provide you with two pieces of information that you should not share with anyone, your issuer id and your issuer secret key.
- The issuer id and secret are required for creating a JWT (JSON web token) that will be used when sending your request to the borderless API to ensure that you are the one requesting the payments be sent.
- We will also provide you with a suite of bank accounts for your sandbox environment. These will be unique to your company.
Once you have those enabled, you will need to create a sandbox environment account where you can begin testing requests. In order to make an On-Demand Debit, a POST request must be sent to the On-Demand Debit endpoint. This post request can be made either manually (using Postman or similar) or programmatically. Contact your account manager for staging and production location endpoints.
Step 3: Access Sandbox Environment
3.A. Create Your Sandbox Account
Once you have an account registered, contact borderless support in order to enable mass payouts for your account.
3.B. Create Your Sandbox Users
In order to test our Mass Payout functionality in our Sandbox environment, you will need to create Sandbox users. In order to do so, you use the following sandbox endpoint and create test accounts using the bank data provided with your API key.Ā
Here are some quick video tutorials on how to create an account:Ā
- How to register and verify your email
- How to add a bank account – Use your sandbox bank credentials. If you are having difficulty, contact your account manager.Ā
- How to upload ID (Optional) Some accounts may require uploading an ID. If you need an ID for your Sandbox accounts, contact your account manager.Ā
Step 4: Follow Our Guide
You are all set to get started. Follow the integration guide below to start debiting your clients on-demand using code with $0 wire fees. If you have any questions, please contact support here.Ā
On-Demand Debit API Guide
Ready to integrate our On-Demand Debit API? Follow these simple steps to get started today!
Registering Users
In order to make payments to your clients, they must first be registered with borderless. To do this, your marketplace or company must inform your clients to create an account with borderless. They can simply go to our sign up page on our website. Your account manager has amazing resources such as email templates, blog posts and more to guide you through this process.
By creating an account, they will create their unique borderless identifier which is called a Handle “@ClientName”. This Handle is important to debit payments from your clients as you no longer need to collect any banking information. You can choose to collect your client’s Handle by creating an entry field in your application for your users. Check out the Data Requirements section for more information about Handles.Ā
Authorization Header
Request payloads must be signed with client’s private key. borderless validates the signature using the client’s private key set which is given at onboarding. If you do not have an account API key, request your API key today.
- Inside the POST request header, there must be a key of āauthorizationā with a value that is a JWT. The payload of the JWT must provide a key of āissuerā that points to the value of your borderless issuer id.
- This JWT must be signed with the provided borderless secret key in order for payments to be executed. Without signing the key payments cannot be verified to come from your account.
- For help manually generating a JWT see: https://jwt.io/
- We recommend the jsonwebtoken npm package: https://www.npmjs.com/package/jsonwebtoken
Create Your Plan
Create Your Plan
Currently, we do not offer the ability to create plans using our API. To get started, go to your borderless dashboard to create your On-Demand Direct Debit Plan.Ā
- Step 1: Go to Plans and click “Create Plan”
- Step 2: Select Plan type “On-Demand Plan”
- Step 3: Enter On-Demand Plan details such as plan name and maximum amount.
- Step 4 (Optional): Invite customers by email or using handles. You can also have a general link for your plan.Ā
Retrieve Plan Id - Only For API Use
You will need to retrieve the planid from your dashboard to start using our On-Demand Debit API as it is a required field. You can retrieve the planid from clicking “View” to see plan details. Here is an example of where you can find it.Ā
Customer On-Demand Debit Post Request
Data Requirement: /CustomerOnDemandDebit
Provide the following data requirements when sending a POST request to the On-Demand API endpoint. The body of the request should contain a JSON object with the the following information:
- Amount – Number – The amount you wish to debit the plan subscriber. A non-negative amount in your home currency to debit from the customer. If the subscriber is an international clients, borderless auto-detects the their currency and debits the equivalent amount of the plan’s amount with better exchange rates than most banks or PayPal. The funds will be debited in their home currency and delivered to the your bank account in your home currency.
- Description – String – The description you would like to be attached to the On Demand Payment with 60 characters max. This will be shown to the customer. Maximum number of characters is 60 characters including spaces.
- PlanId– String – The borderless planId of which this customer is a member of. This is available in the borderless dashboard when you click view plan details.Ā
- Handle – String –Ā The borderless username of the customer you would like to debit, without the “@” symbol. This is a unique identifier for each account. This data needs to be collected prior to making payments. This avoids the need for you to collect banking information helping you reduce risk and limiting data liability. We recommend that your customers share this data on your platform for you to store in your database.
Example of Body Request
Customer On-Demand Debit Response
Successful Response
With both the correct header authorization and the correctly filled out body your post request is ready to send. After sending the requests you should receive a response similar to the following below. Please note that your request may take up to 10 seconds for the response to appear
Response With Errors
You may also encounter some errors with your payments that will be relayed in the response. An instance of this would be if a payment being debited from an account where the account handle does not exist. Refer to the common errors section below for additional error examples.Ā
Add Customer To Recurring Payment Plan Post Request
Data Requirements: /AddCustomerToRecurringPaymentPlan
Provide the following data requirements when sending a POST request to the Add Customer To Recurring Plan endpoint. The body of the request should contain a JSON object with the the following information:
- PlanId– String – The borderless planId of which you want to invite a customer to subscribe to. This is available in the borderless dashboard when you click view plan details.
- Customers – Array – Array of objects containing either a key of āhandleā or āemailā with values that correspond to the customer you wish to add to the plan. If both are given, the handle (customer handle without the @ ) will be used.
Example of Body Request
Add Customer To Recurring Payment Plan Response
Successful Response
Response With Errors
You may also encounter some errors with your invitations that will be relayed in the response. An instance of this would be if a request not contains an invalid handle or invalid email. Refer to the common errors section below for additional error examples.Ā
Delete Customer From Plan Post Request
Data Requirement: /DeleteCustomerFromPlan
Provide the following data requirements when sending a POST request to the Add Customer To Recurring Plan endpoint. The body of the request should contain a JSON object with the the following information:
- PlanId– String – The borderless planId of which you want to remove the customer from. This is available in the borderless dashboard when you click view plan details.
- Handle or email must be provided. Handle will be used if both are given.
- Handle (optional) – String – The borderless username of the customer you would like to remove from the plan, without the “@” symbol. This is a unique identifier for each account. This data needs to be collected prior to making payments. This avoids the need for you to collect banking information helping you reduce risk and limiting data liability. We recommend that your customers share this data on your platform for you to store in your database.
- Email (optional) – String – The email of the borderless customer you would like to remove from the plan.
Example of Body Request
Delete Customer From Plan Post Response
Successful Response
Response With Errors
You may also encounter some errors with removing customers from plans. An instance of this would be if your request fails for some reason you will receive a 400 bad request response. Refer to the common errors section below for additional error examples.Ā
Notifications
borderless handles notifications via email and webhook. For example:Ā
- Once a debit is successful, borderless notifies the recipient immediately via email where they can track the payment in real-time.
- Once a customer is added, borderless automatically sends an invite email to the customer.
- Once a customer is removed from a plan, we automatically notify the customer of their removal.
- Once a customer subscribes, we notify the plan owner.
If you would like to be notified via webhooks instead of email, you can use our webhook notifications to keep up-to-date on the On-Demand Direct Debit API. You will also receive webhook notification for incoming payments if you have integrated our E-commerce plugin. Refer to the webhooks section below on how to get started.Ā
Common Errors
We have identified a list of common errors you may encounter when you integrate our API. Here is a list of a few and how to solve them:Ā
- No issuer provided – In the authorization header, there is no key of issuer in the payload of the JWT.
- On-Demand Debit API not enabled for this account or incorrect token signature – On-Demand Debit have not been enabled for this account or the provided authorization jwt is not signed with the correct secret.
- No payment information given for on-demand debit – The body of the request is missing the payment amount or description.
- Could not find handle for āXXXXā – Unable to find the account for the provided handle.
- Could not find customer when removing customer from plan.
- Cannot add yourself to an automated direct debit plan.
- Your debit amount exceeded the maximum debit of a plan.
Webhooks
Setup Webhooks
Using webhooks allows us to communicate with your system in real time whenever one of your clients pays with borderlessā¢ or whenever you complete an API Request.
A webhook is a notification sent from borderless when an event is triggered without the need to submit a request.Ā borderless will send an HTTP POST request containing the data that is created, to your webhook listener URL.
To get started, you will need a secure URL on your server that is ready to accept and process a POST request containing a JWT in the body. For your security, we encode each webhook with a unique key (“Secret Token”) that you will use to decode and verify our updates to your system.
To enable webhooks, go to your Developer tab in your Dashboard and add your URL. Go to Sandbox DashboardĀ , orĀ Go to Production Dashboard
We strongly advise you to use a URL that uses TLS (https://) for secure communication and that you verify our webhook signature. When your webhook is setup, you will no longer receive email notification when a client pays you.
Customer Subscribed Webhook
When a customer accepts their invitation to the plan and you have webhooks enabled for your account, we will notify you via webhook instead of email.
The webhook received will be similar to the payment notification webhooks in that the information will come encoded in a JWT in the body of the POST request sent to your endpoint. This JWT will be signed with your secret. It is on you to verify that the JWT is correctly signed with your secret before accepting the data received is on behalf of borderless.
An example decoded JWT payload is below:
Error Handling
The borderless GraphQL API uses standard HTTP Status Codes to indicate whether the request succeeded or failed. The errors might also include a message to specific exceptions that happen in processing the request.
The following table indicates the categorizes of the status codes which are used by the borderless GraphQL API:
2xx– The API request was successful4xx– The API request failed5xx– A server error occurred
