Webhooks

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 Webhook received 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. Once decoded, the payload will provide information about the single payment or payout (mass payouts or mass claim payouts) report.

❗️

IMPORTANT

It is your responsibility to verify that the JWT is correctly signed 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 encoded in a JWT in the body of the POST request sent to your endpoint. Once decoded, the payload will provide information about the payment such as its amount, the description, and the status of the payment.

Payment Webhook Structure

ParameterDescriptionType
subSubject of the JWT. It is always gonna be "borderless webhook".String
iatThe time at which the JWT was issued (iat - Issued At).Number
handlehandle of the recipient (either internal or external). (only eligible for payment that failed at submission webhook)String
paymentIdA unique number generated to identify each individual payment.String
amountAmount that has been submitted.Number
currencyThree letter currency code in which payment was made.String
descriptionPayment description.String
statusStatus of the payment. Possible statuses are: PAYMENT_SUCCESSFUL, PAYMENT_RECEIVED, PAYMENT_PENDING, PAYMENT_FAILEDString
reasonReason of why payment submission failed. (only eligible for payment that failed at submission webhook)String
clientPaymentRefPayment reference provided by clientString

You can find examples of decoded JWT payloads, below. Select the different tabs to see additional examples.

{
  "sub": "borderless webhook",
  "iat": 1663611101,
  "paymentId": "0000001",
  "amount": 8.22,
  "currency": "GBP",
  "description": "invoice payment",
  "status": "PAYMENT_RECEIVED",
  "clientPaymentRef": "5f4vv-fv54v4"
}
{
  "sub": "borderless webhook",
  "iat": 1661933387,
  "paymentId": "UATPY103656162",
  "amount": 11,
  "currency": "GBP",
  "description": "no payer fees",
  "status": "PAYMENT_FAILED"
}
{
  "sub": "borderless webhook",
  "iat": 1663613930,
  "handle": "^12345",
  "amount": 15,
  "description": "demo not recognized handle",
  "status": "PAYMENT_FAILED",
  "reason": "Could not find account for handle ^12345. (I-6005)"
}

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 encoded in a JWT in the body of the POST request sent to your endpoint. Once decoded, 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

ParameterDescriptionType
subSubject of the JWT. It is always gonna be "borderless webhook".String
iatThe time at which the JWT was issued (iat - Issued At).Number
batchIdUnique identifier for mass payout.String
successfulPaymentsThe number of successful payments out of total submitted.Number
failedPaymentsThe number of failed payments out of total submitted.Number
totalSubmittedPaymentsThe number of total payments submitted.Number
paymentsReportArray of objects where each object will contain data of either successfully submitted payment or payments that failed at submit.Array of objects
paymentsReport[n].idId of order in which payment was submitted.Number
paymentsReport[n].handleThe handle of the recipient (either internal or external).String
paymentsReport[n].amountThe payment amount submitted.Number
paymentsReport[n].paymentReferenceIdA unique number generated to identify each individual payment (this field is displayed only when payment is submitted successfully).String
paymentsReport[n].submissionStatusEither successful or unsuccessful payment submission.String
paymentsReport[n].causeReason why payment submission was unsuccessful.String
paymentsReport[n].clientPaymentRefPayment reference provided by clientString

You can find an example of a decoded JWT payload, below:

{
  "sub": "borderless webhook",
  "iat": 1663605355,
  "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 encoded in a JWT in the body of the POST request sent to your endpoint. Once decoded, 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 Payout Report Webhook Structure

ParameterDescriptionType
subSubject of the JWT. It is always gonna be "borderless webhook".String
iatThe time at which the JWT was issued (iat - Issued At).Number
batchIdUnique identifier for mass claim payout.String
successfulClaimPaymentsThe number of successful payments out of total submitted.Number
failedClaimPaymentsThe number of failed payments out of total submitted.Number
totalSubmittedClaimPaymentsThe number of total payments submitted.Number
claimPaymentsReportArray of objects where each object will contain data of either successfully submitted payment or payments that failed at submit.Array of objects
paymentsReport[n].idId of order in which payment was submitted.Number
paymentsReport[n].emailEmail address of the recipient.String
paymentsReport[n].handleThe handle of the recipient. (Only if the email is already registered with borderless™ and has associated handle)String
paymentsReport[n].beneCountryTwo letter country code of the recipient.String
paymentsReport[n].amountThe payment amount submitted.Number
paymentsReport[n].paymentReferenceIdA unique number generated to identify each individual payment (this field is displayed only when payment is submitted successfully).String
paymentsReport[n].submissionStatusEither successful or unsuccessful payment submission.String
paymentsReport[n].paymentLinkPayment link that we send to recipient to claim their payment.String
paymentsReport[n].causeReason why payment submission was unsuccessful.String

You can find an example of a decoded JWT payload, below:

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