In This Section

In the Webhooks section of the borderless™ documentation you will find:

Definition of Webhook
Using Webhooks
Setting Up Webhooks
Payment Webhook
Mass Payout Report Webhook
Mass Claim Payout Report Webhook

What is a Webhook?

A Webhook is a notification sent from borderless™ when an event is triggered (without the need for you to submit a request). 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.

Using Webhooks

When an event is triggered, borderless™ will send an HTTP POST request containing the data that is created to your Webhook listener URL.

The POST request will have json body containing webhook information and two custom headers: x-borderless-webhook and x-borderless-webhook-timestamp. To verify the webhook and ensure it came from borderless™ visit How To Verify Webhooks section.

❗️
IMPORTANT
It is your responsibility to verify webhook signature with your secret before accepting the data received is on behalf of borderless™.

👍
Pro Tip
Your webhook secret can be found at the Developer Dashboard after enabling webhooks.

Setting Up Webhooks

To get started setting up webhooks, please refer to the Webhooks Guide

Payment Webhook

When a payment is issued and you have webhooks enabled for your account, we will notify you via webhook instead of email.

The webhook received will come in the json body of the POST request sent to your endpoint. The payload will provide information about the payment such as its amount, the description, and the status of the payment.

Payment Webhook Structure

FieldName	Type	Description	Required
eventType	Enum	Payment \| Account \| Plan	Yes
paymentEntryType	Enum	RECEIVED_PAYMENT \| CREATED_PAYMENT	Yes
paymentReferenceId	String	This field is present when payment was executed successfully. In some cases where payment is failed upon submission, there is no paymentReferenceId assigned	No
paymentType	Enum	LOCAL \| INTERNATIONAL	No
status	Enum	PENDING \| SCHEDULED \| UNCLAIMED \| REQUESTED \| PROCESSING \| IN_TRANSIT \| COMPLETE \| CANCELED \| DECLINED \| FAILED \| RETURNED	No
payer	String	Payer handle (or email if handle doesn’t exist)	No
description	String	Description of the payment	Yes
amount	Number	If payment entry type is RECEIVED_PAYMENT the value of the field will be amount received in beneficiary bank currency before fee (if beneficiary pays the fee) If payment entry type is CREATED_PAYMENT, amount is the payment amount before fees (if payer pays the fee)	Yes
totalAmount	Number	If payment entry type is RECEIVED_PAYMENT the value of the field will be totalAmount received after the fee (if beneficiary pays the fee) If payment entry type is CREATED_PAYMENT, the value of the field will be totalAmount paid after the fee (if payer pays the fee)	Yes
fee	Number	If payment entry type is RECEIVED_PAYMENT the value of the field will be fee amount of beneficiary (if beneficiary pays the fee) If payment entry type is CREATED_PAYMENT, the value of the field will be fee amount of payer (if payer pays the fee)	Yes
currency	Enum	3-letter currency code If payment entry type is RECEIVED_PAYMENT currency field reflects beneficiary bank currency If payment entry type is CREATED_PAYMENT currency field reflects payer payment currency	Yes
beneficiary	String	Beneficiary handle (if exists) or email	No
beneficiaryAmount	Number	This field appears only when payment entry type is CREATED_PAYMENT. This field indicates beneficiary amount before fee (if beneficiary pays the fee)	No
beneficiaryFee	Number	This field appears only when payment entry type is CREATED_PAYMENT. This field indicates beneficiary fee amount (if beneficiary pays the fee)	No
beneficiaryTotalAmount	Number	This field appears only when payment entry type is CREATED_PAYMENT. This field indicates beneficiary total amount after fee (if beneficiary pays the fee)	No
beneficiaryCurrency	Enum	This field appears only when payment entry type is CREATED_PAYMENT. This field indicates beneficiary 3 letter currency	No
batchId	String	If payment was executed via mass payout, batchId of the payout will be assigned	No
estimatedArrival	String	ISO Date string of estimated arrival	No
paymentMethod	Enum	BANK_ACCOUNT \| FUNDING_BALANCE	No
clientPaymentRef	String	If payment was executed via api and unique identifier of clientPaymentRef was provided then it will reflect in this field	No
createdAt	String	ISO Date string of when payment was created	No

Examples of payment webhook bodies shown below.

Successfully executed payment (CREATED_PAYMENT)
(this webhook will be sent to payer if payer have webhooks enabled)

{
  "eventType": "Payment",
  "paymentEntrType": "CREATED_PAYMENT",
  "status": "COMPLETE",
  "paymentReferenceId": "UATPYXYZ",
  "amount": 7,
  "fee": 0,
  "totalAmount": 7,
  "currency": "GBP",
  "description": "test pay",
  "beneficiary": "US-Buziness",
  "beneficiaryAmount": 8.5,
  "beneficiaryFee": 0.75,
  "beneficiaryTotalAmount": 7.75,
  "beneficiaryCurrency": "USD",
  "clientPaymentRef": null,
  "paymentMethod": "FUNDING_BALANCE",
  "paymentType": "INTERNATIONAL",
  "estimatedArrival": "2023-10-05T00:00:00.000Z",
  "batchId": null,
  "createdAt": "2023-10-05T15:09:33.187Z"
}

Received Payment webhook (RECEIVED_PAYMENT) 
(this webhook will be sent to beneficiary if beneficiary have webhooks enabled)

{
  "eventType": "Payment",
  "paymentEntrType": "RECEIVED_PAYMENT",
  "status": "PROCESSING",
  "paymentReferenceId": "97230",
  "payer": "US-Buziness",
  "description": "test with attachment",
  "amount": 5.76,
  "fee": 0.51,
  "totalAmount": 5.25,
  "currency": "GBP",
  "clientPaymentRef": null,
  "paymentMethod": "BANK_ACCOUNT",
  "paymentType": "INTERNATIONAL",
  "estimatedArrival": "2023-10-06T00:00:00.000Z",
  "batchId": null,
  "createdAt": "2023-10-05T15:06:06.438Z"
}

Payment webhook of failed payment (Failed upon submission) will have very minimal 
set of fields because there is no tracking for this payment created:

{
  "beneficiary": "^b5dd1",
  "amount": 100,
  "reason": "Financial Institution Request Error",
  "description": "demo pay to LT",
  "status": "FAILED",
  "batchId": "3b738307-7"
}

Mass Payout Report Webhook

When the Mass Payout is completed the report about successful and unsuccessful payments is sent via email. If you have webhooks enabled for your account, we will notify you via webhook as well.

The webhook received will come in the json body of the POST request sent to your endpoint. The payload will provide information about the executed payments, their amounts, statuses, or reasons why we were not able to submit your payments.

Mass Payout Report Webhook Structure

Parameter	Description	Type
batchId	Unique identifier for mass payout.	String
successfulPayments	The number of successful payments out of total submitted.	Number
failedPayments	The number of failed payments out of total submitted.	Number
totalSubmittedPayments	The number of total payments submitted.	Number
paymentsReport	Array of objects where each object will contain data of either successfully submitted payment or payments that failed at submit.	Array of objects
paymentsReport[n].id	Id of order in which payment was submitted.	Number
paymentsReport[n].handle	The handle of the recipient (either internal or external).	String
paymentsReport[n].amount	The payment amount submitted.	Number
paymentsReport[n].paymentReferenceId	A unique number generated to identify each individual payment (this field is displayed only when payment is submitted successfully).	String
paymentsReport[n].submissionStatus	Either successful or unsuccessful payment submission.	String
paymentsReport[n].cause	Reason why payment submission was unsuccessful.	String
paymentsReport[n].clientPaymentRef	Payment reference provided by client	String

You can find an example of a Mass Payout Report body, below:

{
  "batchId": "aaa00000-a",
  "successfulPayments": 2,
  "failedPayments": 2,
  "totalSubmittedPayments": 4,
  "paymentsReport": [
    {
      "id": 1,
      "handle": "MaltaPerson",
      "amount": 10,
      "submissionStatus": "FAILED",
      "cause": "This payment is below the minimum payment amount. Increase your payment amount or contact support. (I-6008)"
    },
    {
      "id": 2,
      "handle": "FrenchBusiness",
      "amount": 24,
      "paymentReferenceId": "65552",
      "submissionStatus": "SUCCESS",
  		"clientPaymentRef": "5f4vv-fv54v4"
    },
    {
      "id": 3,
      "handle": "^00000",
      "amount": 11,
      "paymentReferenceId": "65544",
      "submissionStatus": "SUCCESS"
    },
    {
      "id": 4,
      "handle": "^aaaaa",
      "amount": 23,
      "submissionStatus": "FAILED",
      "cause": "Could not find account for handle ^aaaaa. (I-6005)"
    }
  ]
}

Mass Claim Payout Report Webhook

When the Mass Claim Payout is completed the report about successful and unsuccessful payments is sent via email. If you have webhooks enabled for your account, we will notify you via webhook as well.

The webhook received will come in a json body of the POST request sent to your endpoint. The payload will provide information about the sent or executed payments, their amounts, statuses, or reasons why we were not able to submit your payments.

Mass Claim Payout Report Webhook Structure

Parameter	Description	Type
batchId	Unique identifier for mass claim payout.	String
successfulClaimPayments	The number of successful payments out of total submitted.	Number
failedClaimPayments	The number of failed payments out of total submitted.	Number
totalSubmittedClaimPayments	The number of total payments submitted.	Number
claimPaymentsReport	Array of objects where each object will contain data of either successfully submitted payment or payments that failed at submit.	Array of objects
paymentsReport[n].id	Id of order in which payment was submitted.	Number
paymentsReport[n].email	Email address of the recipient.	String
paymentsReport[n].handle	The handle of the recipient. (Only if the email is already registered with borderless™ and has associated handle)	String
paymentsReport[n].beneCountry	Two letter country code of the recipient.	String
paymentsReport[n].amount	The payment amount submitted.	Number
paymentsReport[n].paymentReferenceId	A unique number generated to identify each individual payment (this field is displayed only when payment is submitted successfully).	String
paymentsReport[n].submissionStatus	Either successful or unsuccessful payment submission.	String
paymentsReport[n].paymentLink	Payment link that we send to recipient to claim their payment.	String
paymentsReport[n].cause	Reason why payment submission was unsuccessful.	String

You can find an example of a Mass Claim Payout Report body, below:

{
  "batchId": "bbb00000-b",
  "successfulClaimPayments": 2,
  "failedClaimPayments": 2,
  "totalSubmittedClaimPayments": 4,
  "claimPaymentsReport": [
    {
      "id": 1,
      "email": "borderless@getborderless.com",
      "beneCountry": "US",
      "amount": 23,
      "submissionStatus": "UNSUCCESSFUL",
      "cause": "You cannot pay yourself. (I-4703)"
    },
    {
      "id": 2,
      "email": "recipientNo1@getborderless.com",
      "beneCountry": "GB",
      "amount": 32,
      "submissionStatus": "SENT",
      "paymentLink": "http://localhost/claim-payment?paymentId=5df4df45sd4f54sdf4ff5"
    },
    {
      "id": 3,
      "email": "clientNo1@getborderless.com",
      "handle": "Veronika-Person",
      "beneCountry": "US",
      "amount": 10,
      "paymentReferenceId": "65606",
      "submissionStatus": "SUCCESS"
    },
    {
      "id": 4,
      "email": "recipientNo1@getborderless.com",
      "amount": 5,
      "submissionStatus": "UNSUCCESSFUL",
      "cause": "This payment is below the minimum payment amount. Increase your payment amount, specify country or contact support. (I-6008)"
    }
  ]
}