openapi: 3.0.2
info:
title: TransferZero Account Debits Webhooks API
description: Reference documentation for the TransferZero API V1
version: '1.0'
servers:
- url: https://api-sandbox.transferzero.com/v1
- url: https://api.transferzero.com/v1
security:
- AuthorizationKey: []
AuthorizationNonce: []
AuthorizationSignature: []
- AuthorizationKey: []
AuthorizationSecret: []
tags:
- name: Webhooks
paths:
/webhooks:
get:
tags:
- Webhooks
summary: Listing webhooks
description: Get a list of created webhooks
operationId: get-webhooks
parameters:
- name: page
in: query
description: The page number to request (defaults to 1)
required: false
schema:
type: integer
example: 1
- name: per
in: query
description: The number of results to load per page (defaults to 10)
required: false
schema:
type: integer
example: 10
responses:
'200':
description: Array of webhooks requested. A paginated list of the webhooks created by the requesting API key
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDefinitionListResponse'
'401':
description: Authentication information is missing or invalid.
'500':
description: Internal Server Error.
x-group-parameters: true
post:
tags:
- Webhooks
summary: Creating a webhook
description: 'Creates a new webhook, subscribing the provided endpoint to the specified event(s)
'
externalDocs:
description: More information about webhooks
url: https://docs.transferzero.com/docs/architecture/#webhooks
operationId: post-webhooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDefinitionRequest'
example:
webhook:
url: http://myhost.com/for/transaction.paid_in
events:
- transaction.paid_in
metadata:
my: data
required: true
responses:
'201':
description: Details of created webhook
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDefinitionResponse'
'401':
description: Authentication information is missing or invalid.
'422':
description: Webhook details and errors
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDefinitionResponse'
'500':
description: Internal Server Error.
callbacks:
recipient:
'{$request.body#/webhook/url}':
post:
description: Callback object returning details on the triggered recipient event for example when a payment is unsuccessful and there's an error
externalDocs:
description: More information about webhooks
url: https://docs.transferzero.com/docs/architecture/#webhooks
operationId: trigger-recipient-webhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecipientWebhook'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times
x-callback-request: true
transaction:
'{$request.body#/webhook/url}':
post:
description: Callback object returning details on the triggered transaction event, for example when a transaction gets paid out
externalDocs:
description: More information about webhooks
url: https://docs.transferzero.com/docs/architecture/#webhooks
operationId: trigger-transaction-webhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionWebhook'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times
x-callback-request: true
sender:
'{$request.body#/webhook/url}':
post:
description: Callback object returning details on the triggered sender event, for example when a sender gets approved
externalDocs:
description: More information about webhooks
url: https://docs.transferzero.com/docs/architecture/#webhooks
operationId: trigger-sender-webhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SenderWebhook'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times
x-callback-request: true
document:
'{$request.body#/webhook/url}':
post:
description: Callback object returning details on the triggered document event
externalDocs:
description: More information about webhooks
url: https://docs.transferzero.com/docs/architecture/#webhooks
operationId: trigger-document-webhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentWebhook'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times
x-callback-request: true
payout_method:
'{$request.body#/webhook/url}':
post:
description: Callback object returning details on the triggered payout method event
externalDocs:
description: More information about webhooks
url: https://docs.transferzero.com/docs/architecture/#webhooks
operationId: trigger-payout-method-webhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutMethodWebhook'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times
x-callback-request: true
/webhooks/{Webhook ID}:
get:
tags:
- Webhooks
summary: Find a webhook's details
description: Look up a webhook's details with its ID
operationId: get-webhook
parameters:
- name: Webhook ID
in: path
description: 'The ID of the Webhook to look up
Example: `/v1/webhooks/9d4d7b73-a94c-4979-ab57-09074fd55d33`'
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Webhook details
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDefinitionResponse'
'401':
description: Authentication information is missing or invalid.
'404':
description: Resource Not Found.
'500':
description: Internal Server Error.
x-group-parameters: true
delete:
tags:
- Webhooks
summary: Unsubscribing from a webhook
description: Unsubscribes from a webhook specified
operationId: delete-webhook
parameters:
- name: Webhook ID
in: path
description: 'The ID of webhook to cancel.
Example: `/v1/webhooks/9d4d7b73-a94c-4979-ab57-09074fd55d33`'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDefinitionResponse'
'401':
description: Authentication information is missing or invalid.
'404':
description: Resource Not Found.
'422':
description: Webhook details and errors
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDefinitionResponse'
'500':
description: Internal Server Error.
/webhooks/events:
get:
tags:
- Webhooks
summary: Find possible webhook events
description: Fetching possible webhook events
operationId: get-webhook-events
responses:
'200':
description: Webhook events
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDefinitionEventListResponse'
'401':
description: Authentication information is missing or invalid.
'500':
description: Internal Server Error.
x-group-parameters: true
components:
schemas:
Document:
required:
- upload
- upload_file_name
type: object
properties:
upload:
type: string
description: Base64 encoded data uri of an image/pdf file or a fully qualified url
example: data:image/png;base64,iVBORw0KGg...lFTkSuQmCC
url:
type: string
description: URL of the document location
example: https://bitpesa-documents.amazonaws.com/document.pdf
upload_file_name:
type: string
description: Name of the upload
example: example.png
metadata:
type: object
description: Metadata of document
example: {}
upload_content_type:
type: string
example: image/png
upload_file_size:
type: integer
example: 30255
category:
type: string
description: uncategorised
readOnly: true
side:
type: string
description: The side of the KYC ID. One of 'front' or 'back'
readOnly: true
enum:
- front
- back
document_type:
type: string
description: This is a brief description of the document type
example: certificate_of_business_name_registration
issuing_country:
type: string
description: Issuing country of ID in 2-character alpha ISO 3166-2 country format
readOnly: true
example: NG
id:
type: string
format: uuid
readOnly: true
example: ebe9bc0b-f2f6-4ce8-802a-8b79912d041e
document_id:
type: string
description: Document ID issued by government
example: XYZ12345
expiry_date:
type: string
description: Document expiry date issued by government
format: date
source:
type: string
description: Determines the document's source. Default value "Manual"
example: Manual
errors:
additionalProperties:
type: array
readOnly: true
items:
$ref: '#/components/schemas/ValidationErrorDescription'
description: The fields that have some problems and don't pass validation
readOnly: true
example:
phone_number:
- error: invalid
documents:
- error: blank
example:
metadata: {}
side: front
upload: data:image/png;base64,iVBORw0KGg...lFTkSuQmCC
expiry_date: '2000-01-23'
upload_file_name: example.png
upload_content_type: image/png
source: Manual
document_id: XYZ12345
url: https://bitpesa-documents.amazonaws.com/document.pdf
issuing_country: NG
id: ebe9bc0b-f2f6-4ce8-802a-8b79912d041e
upload_file_size: 30255
category: category
errors:
phone_number:
- error: invalid
documents:
- error: blank
document_type: certificate_of_business_name_registration
PayoutMethodDetailsMADCash:
required:
- first_name
- last_name
- phone_number
- sender_identity_card_id
- sender_identity_card_type
type: object
properties:
first_name:
type: string
last_name:
type: string
phone_number:
type: string
sender_identity_card_type:
$ref: '#/components/schemas/PayoutMethodIdentityCardTypeEnum'
sender_identity_card_id:
type: string
sender_city_of_birth:
type: string
sender_country_of_birth:
type: string
sender_gender:
$ref: '#/components/schemas/PayoutMethodGenderEnum'
reason:
type: string
identity_card_type:
$ref: '#/components/schemas/PayoutMethodIdentityCardTypeEnum'
identity_card_id:
type: string
birth_date:
type: string
description: Date of birth of recipient
format: date
description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+212537718685\"\n # Mandatory; E.164 international format\n \"sender_identity_card_type\" => \"O\",\n # Mandatory; Values: \"O\": Other, \"PP\": Passport, \"ID\": National ID\n \"sender_identity_card_id\" => 'AB12345678',\n # Mandatory\n \"sender_city_of_birth\" => \"London\",\n # Optional\n \"sender_country_of_birth\" => \"GB\",\n # Optional; ISO 2-letter format\n \"sender_gender\" => \"M\",\n # Optional; Values: \"M\": Male, \"F\": Female\n \"reason\" => \"Remittance payment\",\n # Optional; Default value is 'Remittance payment'\n \"identity_card_type\" => \"ID\",\n # Optional; Values: \"PP\": Passport, \"ID\": National ID\n \"identity_card_id\" => 'AB12345678'\n # Optional\n}\n```\n\nPlease note when sending MAD::Cash payments you should subscribe to the recipient.pending webhook, as that will broadcast the payment reference ID the customer need to use to obtain the funds.\nExample webhook response excerpt -\n\n```JSON\n{\n (...)\n \"state\":\"pending\",\n \"metadata\": {\n \"payment_reference\":\"9M5GJRJUBCY\"\n },\n (...)\n}\n```\n\nThe reference can also be provided optionally for MAD::Cash, but if you want to use this functionality please contact us for more details."
PayoutMethodDetailsXAFBank:
required:
- first_name
- iban
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
iban:
type: string
bank_account:
type: string
bank_name:
type: string
bank_country:
type: string
bank_code:
type: string
sort_code:
type: string
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
birth_date:
type: string
description: Date of birth of recipient
format: date
description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"iban\": \"CM2110033052090901100045910\", # IBAN format\n \"bank_account\": \"09011000459\",\n \"bank_name\": \"United Bank for Africa - Cameroon\",\n \"bank_country\": \"CM\", # ISO country code for Cameroon\n \"bank_code\": \"10033\",\n \"sort_code\": \"10\",\n \"transfer_reason\": \"personal_account\"\n}\n```\n\nSee [XAF Bank](https://docs.transferzero.com/docs/payout-details/#xafbank) documentation for the bank_code and transfer_reason lists"
PayoutMethodDetailsGBPBank:
required:
- first_name
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
iban:
type: string
bank_account:
type: string
sort_code:
type: string
bic:
type: string
bank_name:
type: string
narration:
type: string
birth_date:
type: string
description: Date of birth of recipient
format: date
description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"iban\": \"GB45LOYD60161331926819\", // Required if no `bank_account` and `sort_code`\n \"bank_account\": \"12345678\", // Required if `iban` is not present\n \"sort_code\": \"123456\", // Required if `bank_account` is present\n \"bic\": \"CHASUS33XXX\" // Optional\n \"bank_name\": \"JPMorgan Chase Bank\", // Optional\n \"narration\": \"Birthday Gift\" // Optional\n}\n```"
PayoutMethodDetailsCADBank:
required:
- bank_account
- bank_code
- branch_code
- first_name
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
bank_account:
type: string
bank_code:
type: string
branch_code:
type: string
birth_date:
type: string
description: Date of birth of recipient
format: date
description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_account\": \"123456789\",\n \"bank_code\": \"003\",\n \"branch_code\": \"12345\"\n}\n```\nSee [CAD Bank](https://docs.transferzero.com/docs/payout-details/#cadbank) documentation for the bank_code list"
PayoutMethodDetailsBRLBank:
required:
- city
- first_name
- identity_card_id
- last_name
- postal_code
- transfer_reason
type: object
properties:
first_name:
type: string
last_name:
type: string
city:
type: string
postal_code:
type: string
phone_number:
type: string
bank_code:
type: string
branch_code:
type: string
bank_account:
type: string
bank_account_type:
$ref: '#/components/schemas/PayoutMethodBankAccountTypeEnum'
pix_key_type:
$ref: '#/components/schemas/PayoutMethodPixKeyTypeEnum'
pix_key_value:
type: string
identity_card_id:
type: string
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
birth_date:
type: string
description: Date of birth of recipient
format: date
description: "PIX Payment:\n```JSON\n \"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"city\": \"Brasilia\",\n \"postal_code\": \"70070\",\n \"phone_number\": \"+552112345678\", // E.164 international format\n \"pix_key_type\": \"email\",\n \"pix_key_value\": \"person@example.com\",\n \"identity_card_id\": \"01234567890\", // CPF or CNPJ\n \"transfer_reason\": \"personal_account\"\n }\n```\n\nTED Payment:\n```JSON\n \"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"city\": \"Brasilia\",\n \"postal_code\": \"70070\",\n \"phone_number\": \"+552112345678\", // E.164 international format\n \"bank_code\": \"104\",\n \"branch_code\": \"00001\",\n \"bank_account\": \"0009795493\",\n \"bank_account_type\": \"10\",\n \"identity_card_id\": \"01234567890\", // CPF or CNPJ\n \"transfer_reason\": \"personal_account\"\n }\n```\n\nSee [BRL Bank](https://docs.transferzero.com/docs/payout-details/#brlbank) documentation for the bank_code and transfer_reason lists"
PayinMethod:
type: object
properties:
type:
type: string
description: 'Describes how the payment should be requested from the sender.
Possible values:
- `GHS::Mobile`: GHS mobile collections
- `UGX::Mobile`: UGX mobile collections
- `XOF::Mobile`: XOF mobile collections
- `NGN::Bank`: NGN bank collections
- `EUR::Bank`: EUR IBAN collections
- `GBP::Bank`: GBP IBAN collections
'
example: GHS::Mobile
ux_flow:
$ref: '#/components/schemas/PayinMethodUxFlow'
in_details:
$ref: '#/components/schemas/PayinMethodDetails'
id:
type: string
format: uuid
readOnly: true
example: 97e79719-06e4-4794-aeeb-d2d9415d983a
state:
$ref: '#/components/schemas/PayinMethodState'
state_reason_details:
$ref: '#/components/schemas/StateReasonDetails'
out_details:
type: object
description: This will contain the description on where to pay the funds. Please see the [Collections Details](https://docs.transferzero.com/docs/collection-details) in the API documentation on what to expect here.
readOnly: true
instructions:
type: object
description: This will contain the instructions on how to pay the funds. Please see the [Collections Details](https://docs.transferzero.com/docs/collection-details) in the API documentation on what to expect here.
readOnly: true
errors:
additionalProperties:
type: array
readOnly: true
items:
$ref: '#/components/schemas/ValidationErrorDescription'
description: The fields that have some problems and don't pass validation
readOnly: true
example:
phone_number:
- error: invalid
documents:
- error: blank
description: This describes the specific details on how the funds should be collected from the sender.
example:
type: GHS::Mobile
ux_flow: ussd_popup
in_details:
phone_number: '+233541299999'
mobile_provider: vodafone
externalDocs:
description: Collections Details
url: https://docs.transferzero.com/docs/collection-details
RecipientWebhook:
readOnly: true
allOf:
- $ref: '#/components/schemas/Webhook'
- type: object
properties:
object:
$ref: '#/components/schemas/Recipient'
readOnly: true
WebhookDefinitionRequest:
type: object
properties:
webhook:
$ref: '#/components/schemas/WebhookDefinition'
example:
webhook:
id: 1cd580b2-2a1b-4f73-81c8-0308308baef2
url: https://webhook.site/webhooks
events:
- transaction.paid_out
metadata: {}
Transaction:
required:
- input_currency
- recipients
- sender
type: object
properties:
input_currency:
type: string
description: The input currency describes what currency the transaction will be paid in (3-character alpha ISO 4217 currency format). For example if you wish to create an EUR to NGN transaction then input currency should be set to EUR.
example: NGN
payin_methods:
type: array
description: 'Allows setting alternative collections, where funding the transaction is done through alternative means and not via account balance.
For more information please see [Collections from senders](https://docs.transferzero.com/docs/additional-features/#collections-from-senders) in the API documentation'
items:
$ref: '#/components/schemas/PayinMethod'
metadata:
type: object
description: Additional metadata to store on the transaction. If you widh to store your local transaction ID, you should add it here inside a `sendRef` field, and we will return this value back to you in the daily transaction reports.
example:
sendRef: MONEY-TRANSFER-12543
sender:
$ref: '#/components/schemas/Sender'
recipients:
type: array
description: 'The details of where the payment should go. although transactions can support paying out multiple
recipients, usually one is provided.
'
items:
$ref: '#/components/schemas/Recipient'
traits:
$ref: '#/components/schemas/TransactionTraits'
state:
$ref: '#/components/schemas/TransactionState'
input_amount:
type: number
description: The amount that was requested in the input currency
readOnly: true
example: 1000
payin_reference:
type: string
description: The reference number that has to be provided in case the transaction is not funded through account balance
readOnly: true
paid_amount:
type: number
description: The amount that was already paid in to the transaction
readOnly: true
example: 1000
due_amount:
type: number
description: The amount needed to be paid in for the transaction to get funded
readOnly: true
example: 1000
created_at:
type: string
description: The time the transaction was created
format: date-time
readOnly: true
expires_at:
type: string
description: The latest time when the transaction has to be funded, otherwise it will be cancelled
format: date-time
readOnly: true
external_id:
type: string
description: 'Optional ID that is supplied by partner linking it to the partner''s own Transaction ID. Note: if present we will validate whether the sent ID is a duplicate in our system or not.'
example: 806ec63a-a5a7-43cc-9d75-1ee74fbcc026
id:
type: string
format: uuid
readOnly: true
errors:
additionalProperties:
type: array
readOnly: true
items:
$ref: '#/components/schemas/ValidationErrorDescription'
description: The fields that have some problems and don't pass validation
readOnly: true
example:
phone_number:
- error: invalid
documents:
- error: blank
description: "The template of transactions are the following:\n```JSON\n{\n \"input_currency\": // currency to pay in,\n \"sender\":{\n // details of the sender\n },\n \"recipients\":[\n {\n \"requested_amount\": // the amount to pay out,\n \"requested_currency\": // the currency of the amount,\n \"payout_method\":{\n \"type\": // method of the payout,\n \"details\":{\n // details of the recipient\n }\n }\n }\n ],\n \"metadata\": // optional metadata\n}\n```"
example:
metadata:
sendRef: MONEY-TRANSFER-12543
traits:
account_validation: true
auto_refund: true
payin_methods:
- type: GHS::Mobile
ux_flow: ussd_popup
in_details:
phone_number: '+233541299999'
mobile_provider: vodafone
- type: GHS::Mobile
ux_flow: ussd_popup
in_details:
phone_number: '+233541299999'
mobile_provider: vodafone
created_at: '2000-01-23T04:56:07.000+00:00'
payin_reference: payin_reference
external_id: 806ec63a-a5a7-43cc-9d75-1ee74fbcc026
input_amount: 1000
expires_at: '2000-01-23T04:56:07.000+00:00'
due_amount: 1000
sender:
country: NG
metadata: {}
occupation: Accountant
documents:
- id: b6648ba3-1c7b-4f59-8580-684899c84a07
politically_exposed_people:
- id: '40'
name: Ronald Reagan
position: President of the United States
started_date: '1981-01-20T00:00:00.000Z'
ended_date: '1989-01-20T00:00:00.000Z'
sender_id: f9dc79ca-0c39-4add-9f4d-5ad7e6f187fb
birth_date: '2000-01-23'
type: person
amount_monthly_transactions: amount_monthly_transactions
legal_entity_type: privately_owned_company
company_office_number_country: GB
trading_address: trading_address
fingerprint: fingerprint
regulatory_licence_number: regulatory_licence_number
phone_country: NG
aml_officer_phone_country: GB
id: bf9ff782-e182-45ac-abea-5bce83ad6670
state: initial
number_monthly_transactions: number_monthly_transactions
aml_officer_phone: '123123123'
ip: 127.0.0.1
custom_source_of_funds: custom_source_of_funds
registration_date: '2000-01-23'
nationality: NG
trading_name: trading_name
name: name
phone_number: '752403639'
address_description: address_description
trading_country: trading_country
errors:
phone_number:
- error: invalid
documents:
- error: blank
financial_regulator: financial_regulator
company_office_number: '123123123'
purpose_of_opening_account: purpose_of_opening_account
identification_number: AB123456
gender: M
city: Kampala
sales_lead_id: HF6HJVF67
registration_number: registration_number
identification_type: ID
created_at: 2019-01-11T00:00:00.001+0000
external_id: 806ec63a-a5a7-43cc-9d75-1ee74fbcc026
list_of_countries_of_operation:
- Spain
- Germany
- Poland
nature_of_business: personal
street: Fake Street
vat_registration_number: vat_registration_number
country_of_birth: GB
company_website_url: www.azafinance.com
lang: en
first_name: Johnny
source_of_funds: source_of_funds
email: example@home.org
contact_person_email: contact_person_email
number_of_employees_in_company: 250+
onboarding_status: onboarding_status
last_name: English
middle_name: Johnny
declaration: 'Yes'
core_business_activity: core_business_activity
office_phone: office_phone
aml_officer_email: aml_officer_email
estimated_annual_revenue_turnover: estimated_annual_revenue_turnover
postal_code: '798983'
city_of_birth: London
recipients:
- created_at: '2018-06-07T15:12:12.513Z'
editable: true
retriable: true
input_usd_amount: 1031.31
may_cancel: false
metadata: {}
state: canceled
transaction_id: 7901b86c-07cb-4f68-9e25-db48fc5d96d3
transaction_state: manual
payout_method:
id: 97e79719-06e4-4794-aeeb-d2d9415d983a
type: NGN::Bank
details:
bank_code: 058
bank_account: '123456789'
bank_account_type: '10'
last_name: English
first_name: Johnny
metadata:
my: data
exchange_rate: 1036911.90353524
fee_fra
# --- truncated at 32 KB (143 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aza-finance/refs/heads/main/openapi/aza-finance-webhooks-api-openapi.yml