Skip to main content
Payments API Payments Webhooks Onboarding API Receivables API Receivables Webhooks Codes and messages Transfermate Education Documentation
Overview
Payments Action

Payables Webhooks

In addition to the TransferMate Payments service, a webhook service system is available. This is how we keep our Partners updated with the status of their beneficiaries and transactions, and complete the round trip of information back to our users.

As webhooks require TransferMate to reach into our partners systems the method of Authentication which we use is very important. The TransferMate webhook system uses a single key pairing sent in a custom header of each request.

The events can be identified using the event_code. Each number corrilates with an event type. In the below examples, you will see the event_code for each type. It is important to use this as the identifier, instead of the status or description (for example), as these are liable to change.

Understanding and implementing the various Error Codes TransferMate expects back from a webhook call. And deciding and agree on a schedule of retry attempts should one of these errors be encountered.

Payment Actions

Get Updates on the status of payments

Payment Paid

The payment paid webhook is raised once TransferMate has successfully received funds from the user into our local TransferMate account.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "4dc3934f-0865-43b8-8d34-0a813346f3d1",
    "customer_id": "80812345",
    "event_code": "1",
    "event_details": {
        "Unique_Record_id": "T1234567",
        "description": "Payment_Paid",
        "updated_at": "2019-10-24 10:33:24Z",
        "status": "Paid"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Payment Rejected

The payment rejected webhook is raised when the beneficiary bank account rejects the transfer and sends the funds back.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
status_further_info Reject Reason Code. See Reject Reason Codes in Codes and Messages for more information Varchar
description Details about the webhook call Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "1391cc97-45da-40ac-b3f2-e11e5cc05849",
    "customer_id": "80894601",
    "event_code": "3",
    "event_details": {
        "Unique_Record_id": "T3614431",
        "status_further_info": "R03",
        "description": "Payment_Rejected",
        "updated_at": "2022-02-23 13:30:53+00",
        "status": "Rejected"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Payment Cancelled

The payment cancelled webhook is raised when the user requests to cancel the transfer, before the funds have been sent.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "8252d759-d2b3-4ae4-ad2a-5256b9a81aa4",
    "customer_id": "80812345",
    "event_code": "4",
    "event_details": {
        "Unique_Record_id": "T1234567",
        "description": "Payment_Cancelled",
        "updated_at": "2019-10-24 10:33:24Z",
        "status": "Cancelled"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Payment Complete

The payment complete webhook is raised once TransferMate has sent the funds from our TransferMate account to the beneficiary account.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "84588fbe-2036-4edf-be8a-75431eb406e9",
    "customer_id": "80812345",
    "event_code": "2",
    "event_details": {
        "Unique_Record_id": "T1234567",
        "description": "Payment_PaymentComplete",
        "value_date": "2019-10-24",
        "updated_at": "2019-10-24 10:33:24Z",
        "status": "Payment Complete"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Credit

The credit webhook is raised once funds have been added to a Global Account.

Success response Body Payload Example

The response body includes the following parameters:

rail_type
Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id ID of the customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object that holds further details about the webhook call Varchar
Unique_Record_id TransferMates' unique Identifier for the record Varchar
Global_Account The name of the Global Account that is being credited Varchar
ga_account_id The user_bank_id that is returned in the activate global account Varchar
reference A transaction reference Varchar
currency The currency of the Global Account that is being credited Varchar
amount The amount that is being credited Varchar
payer Payer to the Global Account Varchar
updated_at date field, when the webhook was fired Varchar
status Further details about the webhook call Varchar
rail_type Information on the payment rail used by sender Varchar

Example Success Response

{
  "event_id": "019a5403-ebdb-7266-85ee-26e84787e593",
  "customer_id": "80816177",
  "event_code": "50",
  "event_details": {
    "Unique_Record_id": "T14942860",
    "Global_Account": "",
    "currency": "USD",
    "amount": "10",
    "payer": "",
    "ga_account_id": 607985,
    "reference": "Ref: Fingal County",
    "rail_type": "ACH",
    "description": "Credit",
    "updated_at": "2025-11-05 10:54:11+00",
    "status": "Credit"
  }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Customer Actions

Get Updates on the status of a customer

Customer AML Complete

The customer AML completed webhook is raised when a user has successfully passed all Anti Money Laundering checks in the TransferMate system.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "3511e175-ab2c-40ec-ba5d-49e466c86328",
    "customer_id": "80812345",
    "event_code": "6",
    "event_details": {
        "Unique_Record_id": "80812345",
        "description": "CustomerAMLCompleted",
        "updated_at": "2019-10-24 10:33:24Z",
        "status": "Active"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Customer Bank Account Direct Debit Mandate Success

The customer bank account direct debit mandate success webhook is raised once TransferMate has received a direct debit mandate from the user for one of their bank accounts, and all information is correct and adequate.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "dc213711-092a-469f-95fb-0d818a50ed95",
    "customer_id": "80812345",
    "event_code": "7",
    "event_details": {
        "Unique_Record_id": "12345",
        "description": "CustomerBankAccount_DirectDebitMandate_Success",
        "updated_at": "2019-10-24 10:33:24Z",
        "status": "Active"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Beneficiary Actions

Get Updates on the status of a beneficiary

Beneficiary Active

The beneficiary active webhook is raised when a beneficiary successfully passes all of TransferMates compliance checks. Or a beneficiary which has previously passed these checks is reactivated on the TransferMate system.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "3af0a277-e024-4112-ac12-ce21c5be172e",
    "customer_id": "80812345",
    "event_code": "17",
    "event_details": {
        "Unique_Record_id": "12345",
        "status": "Bene_Active",
        "updated_at": "2019-10-24 10:33:24Z",
        "description": "Active"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Beneficiary Deactive

The beneficiary deactivated webhook is raised when the user deactivated a beneficiary on the TransferMate system.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "d20e81d9-2338-433a-bcad-b1aa02438b33",
    "customer_id": "80812345",
    "event_code": "18",
    "event_details": {
        "Unique_Record_id": "12345",
        "status": "Bene_DeActivated",
        "updated_at": "2019-10-24 10:33:24Z",
        "description": "Inactive"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Beneficiary Pending (Deprecated)

The beneficiary pending webhook is raised in response to a user calling the add beneficiary API endpoint. This is to indicate that TransfeMate has received the beneficiary details and they are currently undergoing compliance checks.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "92a0450b-151c-48da-8e97-3c10e1873f39",
    "customer_id": "80812345",
    "event_code": "20",
    "event_details": {
        "Unique_Record_id": "12345",
        "status": "Bene_Pending",
        "updated_at": "2019-10-24 10:33:24Z",
        "description": "Pending"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts  

Beneficiary Rejected

The beneficiary rejected webhook is raised when TransferMate have rejected the beneficiary as it has failed compliance checks. This beneficiary is deactivated and cannot be reactivated.

Success response Body Payload Example

The response body includes the following parameters:

Field Description Type
event_id Unique identifier for this specific webhook call Varchar
customer_id Id of customer requesting the webhook Varchar
event_code Identifier for webhook type. Varchar
event_details object which holds further details about the webhook call Varchar
Unique_Record_id TransferMates unique Identifier for the record Varchar
description Details about the webhook call Varchar
Value_date Date the funds are expected to be with the beneficiary Varchar
updated_at date field, when the webhook was fired Varchar
status further details about the webhook call Varchar

Example Success Response

{
    "event_id": "d07b8a67-23e6-4451-9c3e-6328dd60d36e",
    "customer_id": "80812345",
    "event_code": "19",
    "event_details": {
        "Unique_Record_id": "12345",
        "status": "Bene_Rejected",
        "updated_at": "2019-10-24 10:33:24Z",
        "description": "Rejected"
    }
}

Error response Body Payload Example

The error response body includes the following parameters:

Field Description Type
400 Bad Request - will trigger automatic retry attempts  
401 Unauthorised - will NOT trigger automatic retry attempt  
403 Forbidden - will NOT trigger automatic retry attempts  
404 Not Found - will NOT trigger automatic retry attempts  
500 Bad Request - will trigger automatic retry attempts  
501 Bad Request - will NOT trigger automatic retry attempts  
503 Service Unavailable - will trigger automatic retry attempts