openapi: 3.0.2
info:
title: TransferZero Account Debits Transactions 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: Transactions
paths:
/transactions:
get:
tags:
- Transactions
summary: Get a list of transactions
description: Retrieves a paginated list of the Transactions created by your API key.
operationId: get-transactions
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
- name: external_id
in: query
description: 'Allows filtering results by `external_id`.
Example: `/v1/senders?external_id=26ec8517-2f0d-48c0-b74f-0bccb9ab3a87`'
required: false
schema:
type: string
- name: sender_id
in: query
description: 'Allows filtering results by `sender_id`.
Example: `/v1/transactions?sender_id=b41d3cb7-6c54-4245-85fc-8e30690eb0f7`'
required: false
schema:
type: string
- name: transactions_type
in: query
description: 'Allows filtering results by `transactions_type`.
Example: `/v1/transactions?transactions_type=automated`'
required: false
schema:
type: string
enum:
- automated
- manual
responses:
'200':
description: A paginated list of the transactions created by your API key.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionListResponse'
'400':
description: Bad Request - server was unable to process the request due to invalid syntax.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorStatus'
example: "{\n \"status\": 400,\n \"error\": \"Bad Request\"\n}"
'401':
description: Authentication information is missing or invalid.
'500':
description: Internal Server Error.
x-group-parameters: true
post:
tags:
- Transactions
summary: Creates a new transaction
description: 'Transactions are the main objects in the TransferZero API, so it''s important to understand how to create and manage them.
Transactions facilitate money movement from one Sender in a specific currency to one or multiple Recipients in another currency.
The main flow of a successful transaction flow is the following -
- Transaction is created linking the Sender to the Recipient(s) with the requested amounts.
- Once the sender is KYC''d and approved the transaction can be funded.
- Once the transaction is funded, we will initiate the payout to the recipient(s).
- After the recipient (or all recipients) has received the money, the transaction is finished.'
externalDocs:
description: API Documentation - Create Transaction
url: https://docs.transferzero.com/docs/transaction-flow/
operationId: post-transactions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
required: true
responses:
'201':
description: Transaction has been created
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'400':
description: Bad Request - server was unable to process the request due to invalid syntax.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorStatus'
example: "{\n \"status\": 400,\n \"error\": \"Bad Request\"\n}"
'401':
description: Authentication information is missing or invalid.
'422':
description: Error - transaction payload is invalid (includes errors object and duplicate transaction/sender if external_id is already in use)
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'500':
description: Internal Server Error.
/transactions/calculate:
post:
tags:
- Transactions
summary: Calculates transaction amounts for a transaction payload
description: Calculates the input, output and fee amounts for the recipients in a transaction payload
operationId: calculate-transactions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
required: true
responses:
'200':
description: Transaction object with calculated values
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'401':
description: Authentication information is missing or invalid.
'422':
description: Error - transaction payload is invalid (includes errors object)
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'500':
description: Internal Server Error.
/transactions/validate:
post:
tags:
- Transactions
summary: Validates a transaction payload
description: Validates fields in a transaction payload and displays invalid or missing fields
operationId: validate-transactions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
required: true
responses:
'200':
description: Success - transaction payload is valid
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'401':
description: Authentication information is missing or invalid.
'422':
description: Error - transaction payload is invalid (includes errors object)
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'500':
description: Internal Server Error.
/transactions/create_and_fund:
post:
tags:
- Transactions
summary: Creates a new transaction and funds it from account balance
description: 'This endpoint creates a transaction and funds it from an account balance. You must ensure that you have established an account with us in the pay-in currency of the transactions you wish to create, and that this account is sufficently funded, before calling this endpoint.
Note that the <pre>external_id</pre> field is required for requests to this endpoint.'
operationId: create-and-fund-transaction
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
required: true
responses:
'201':
description: Transaction has been created and funded
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'400':
description: Bad Request - server was unable to process the request due to invalid syntax.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorStatus'
example: "{\n \"status\": 400,\n \"error\": \"Bad Request\"\n}"
'401':
description: Authentication information is missing or invalid.
'422':
description: Error - transaction payload is invalid (includes errors object and duplicate transaction/sender if external_id is already in use)
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'500':
description: Internal Server Error.
/transactions/{Transaction ID}:
get:
tags:
- Transactions
summary: Fetch a single transaction
description: 'Finds and returns a Transaction created by the requesting API key, using
the provided Transaction ID.'
operationId: get-transaction
parameters:
- name: Transaction ID
in: path
description: 'ID of the transaction.
Example: `/v1/transactions/bf9ff782-e182-45ac-abea-5bce83ad6670`'
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Transaction object
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'400':
description: Bad Request - server was unable to process the request due to invalid syntax.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorStatus'
example: "{\n \"status\": 400,\n \"error\": \"Bad Request\"\n}"
'401':
description: Authentication information is missing or invalid.
'404':
description: Resource Not Found.
'500':
description: Internal Server Error.
x-group-parameters: true
/transactions/{Transaction ID}/payin:
post:
tags:
- Transactions
summary: Creates a fake payin for transaction
description: 'This method is available only in sandbox environment and is supposed to be used only for testing integration.
It allows you to emulate a payin without paying actual money.
'
operationId: payin-transaction
parameters:
- name: Transaction ID
in: path
description: 'ID of the transaction to payin.
Example: `/v1/transactions/bf9ff782-e182-45ac-abea-5bce83ad6670/payin`'
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayinMethodRequest'
required: true
responses:
'200':
description: Transaction object
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'401':
description: Authentication information is missing or invalid.
'404':
description: Resource Not Found.
'422':
description: Invalid transaction object (includes errors object)
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'500':
description: Internal Server Error.
/transactions/{Transaction ID}/payout:
post:
tags:
- Transactions
summary: Creates a fake payout for transaction
description: 'This method is available only in sandbox environment and is supposed to be used only for testing.
It allows you to emulate the payout of a transaction after payin.
'
operationId: payout-transaction
parameters:
- name: Transaction ID
in: path
description: 'ID of the transaction to payout.
Example: `/v1/transactions/bf9ff782-e182-45ac-abea-5bce83ad6670/payout`'
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Transaction object
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionResponse'
'401':
description: Authentication information is missing or invalid.
'404':
description: Resource Not Found.
'500':
description: Internal Server Error.
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
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
# --- truncated at 32 KB (157 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aza-finance/refs/heads/main/openapi/aza-finance-transactions-api-openapi.yml