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 external_id
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_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_fractional: 2723
requested_amount: 1000.0
requested_currency: USD
input_amount: 908.0
input_currency: UGX
output_amount: 941.51600841
output_currency: NGN
- 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_fractional: 2723
requested_amount: 1000.0
requested_currency: USD
input_amount: 908.0
input_currency: UGX
output_amount: 941.51600841
output_currency: NGN
paid_amount: 1000
state: initial
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
input_currency: NGN
errors:
phone_number:
- error: invalid
documents:
- error: blank
externalDocs:
description: The Transaction flow
url: https://docs.transferzero.com/docs/transaction-flow/
PayinMethodRequest:
type: object
properties:
payin_method:
$ref: '#/components/schemas/PayinMethod'
example:
payin_method:
type: PayinMethod::NGN::Bank
RecipientStateReasonDetails:
anyOf:
- $ref: '#/components/schemas/StateReasonDetails'
PayoutMethodDetailsNGNBank:
required:
- bank_account
- bank_code
- first_name
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
bank_code:
type: string
bank_account:
type: string
bank_account_type:
$ref: '#/components/schemas/PayoutMethodBankAccountTypeEnum'
birth_date:
type: string
description: Date of birth of recipient
format: date
street:
type: string
description: "```JSON\n \"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_code\": \"058\",\n \"bank_account\": \"123456789\",\n \"bank_account_type\": \"10\", # 10 for saving, 20 for current accounts\n \"street\": \"1 Main Street\"\n }\n```\n\nSee [NGN Bank](https://docs.azafinance.com/docs/individual-payments/#ngnbank) documentation for the bank_code"
RecipientState:
type: string
description: 'The state of the recipient. Can be one of the following:
* `initial`: We haven''t initiated the payout yet, you can still cancel the transaction
* `pending`: Payout has been initiated and we''re waiting from a response from the provider. You can try to cancel it at this point, however it will only get cancelled if we get confirmation from our partner that the payment has failed.
* `success`: Payout is done, and the recipient has been paid.
* `error`: There was an error from the provider, you can find more details in the `state_reason` attribute. We will usually retry the transaction at a later date. You can either wait, edit the recipient or cancel the transaction.
* `refunded`: You asked us to cancel the transaction and we refunded the money.
* `manual`: There were too many errors on this transaction, and we stopped retrying. Please edit the recipient, contact us or cancel the transaction.
* `stuck`: We didn''t receive a response from the provider in time, and we don''t know whether it has been paid our not. Please contact us for further details.
* `overpaid`: The recipient was paid out more than was requested (not applicable for most of the payout providers)
* `canceled`: The transaction has been cancelled, and we will refund the money soon
* `exception`: Some exception has happened; please contact TransferZero'
readOnly: true
example: initial
enum:
- initial
- pending
- success
- error
- refunded
- manual
- stuck
- overpaid
- canceled
- exception
PayoutMethodCountryEnum:
type: string
description: 'The country for the pickup or mobile payout.
For USD cash pickup in Nigeria, valid options are:
- `NG`: Nigeria
For XOF cash pickup, valid options are:
- `CI`: Ivory Coast
- `ML`: Mali
- `SN`: Senegal
For XOF mobile payout, valid options are:
- `BJ`: Benin
- `BF`: Burkina Faso
- `CI`: Ivory Coast
- `ML`: Mali
- `SN`: Senegal
- `TG`: Togo
For XAF mobile payout, valid options are:
- `CG`: Congo
- `CM`: Cameroon
- `GA`: Gabon
- `TD`: Chad'
example: SN
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AX
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- KH
- CM
- CA
- CV
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CG
- CD
- CK
- CR
- CI
- HR
- CU
- CY
- CZ
- DK
- DJ
- DM
- DO
- TP
- EC
- EG
- SV
- GQ
- ER
- EE
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IL
- IT
- JM
- JP
- JO
- KZ
- KE
- KI
- KP
- KR
- KV
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MK
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- MS
- ME
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- AN
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RE
- RO
- RU
- RW
- SH
- KN
- LC
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SK
- SI
- SB
- SO
- ZA
- GS
- ES
- LK
- SD
- SR
- SJ
- SZ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TG
- TK
- TO
- TT
- TN
- TR
- TM
- TC
- TV
- UG
- UA
- AE
- GB
- US
- UM
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
PayoutMethodDetailsBWPBank:
required:
- bank_account
- bank_name
- branch_code
- first_name
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
bank_name:
type: string
bank_account:
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_name\": \"Banc ABC\",\n \"bank_account\": \"12345678912345678\",\n \"branch_code\": \"550067\",\n}\n```\nSee [BWP Bank](https://docs.transferzero.com/docs/payout-details/#bwpbank) documentation for the bank_name & branch_code list"
PayoutMethodDetailsBTC:
required:
- address
- first_name
- last_name
- name
type: object
properties:
first_name:
type: string
last_name:
type: string
name:
type: string
address:
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 \"name\": \"Full Name\"\n \"address\": \"n4VQ5YdHf7hLQ2gWQYYrcxoE5B7nWuDFNF\"\n}"
PayoutMethodDetailsBalance:
type: object
properties:
reference:
type: string
description: "```JSON\n\"details\": {\n \"reference\": \"Reference\" // optional\n}\n```"
PayoutMethodDetailsKESMobile:
required:
- first_name
- identity_card_id
- identity_card_type
- last_name
- mobile_provider
- phone_number
- street
- transfer_reason
type: object
properties:
first_name:
type: string
last_name:
type: string
street:
type: string
city:
type: string
phone_number:
type: string
mobile_provider:
$ref: '#/components/schemas/PayoutMethodMobileProviderEnum'
transfer_reason_code:
type: string
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
identity_card_type:
$ref: '#/components/schemas/PayoutMethodIdentityCardTypeEnum'
identity_card_id:
type: string
relationship_to_sender:
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 \"street\": \"1 Linford Street\",\n \"city\": \"Nairobi\",\n \"phone_number\": \"+254123456789\", // E.164 international format\n \"identity_card_type\": \"ID\", // refers to the recipient's ID details; Values: \"PP\": Passport, \"ID\": National ID or \"O\": Other\n \"identity_card_id\": 'AB12345678', // refers to the recipient's ID details\n \"transfer_reason\": \"personal_account\",\n \"mobile_provider\": \"mpesa\",\n \"relationship_to_sender\": \"Aunt\" // Optional\n }\n```\n\nSee [KES Mobile](https://docs.transferzero.com/docs/payout-details/#kesmobile) documentation for transfer_reason lists"
PayoutMethodDetailsGNFMobile:
required:
- first_name
- last_name
- mobile_provider
- phone_number
type: object
properties:
first_name:
type: string
last_name:
type: string
phone_number:
type: string
mobile_provider:
$ref: '#/components/schemas/PayoutMethodMobileProviderEnum'
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\": \"+224444044436\", // E.164 international format\n \"mobile_provider\": \"mtn\"\n}\n```"
PayinMethodDetails:
description: 'Fields needed by the payment processor. Depends on the chose payin type.
See the appropriate model details for more info:
- `NGN::Bank`: see [`PayinMethodDetailsNGNBank`](#model-PayinMethodDetailsNGNBank)
- `GHS::Mobile`: see [`PayinMethodDetailsMobile`](#model-PayinMethodDetailsMobile)
- `UGX::Mobile`: see [`PayinMethodDetailsMobile`](#model-PayinMethodDetailsMobile)
Note that some payin processors don''t require additional input, these include `lhv` through `EUR::Bank` and `GBP::Bank`.
Some providers like `providus` also have all of their fields set as optional, so you might not want to set any values.
To use these providers please set this value to `{}` (an empty hash)
'
oneOf:
- $ref: '#/components/schemas/PayinMethodDetailsNGNBank'
- $ref: '#/components/schemas/PayinMethodDetailsMobile'
- $ref: '#/components/schemas/PayinMethodDetailsBTC'
TransactionRequest:
type: object
properties:
transaction:
$ref: '#/components/schemas/Transaction'
example:
transaction:
input_currency: EUR
sender:
country: US
phone_number: '+256752403639'
email: test@example.com
first_name: Text
last_name: Example
city: City
street: Street
postal_code: '12345'
birth_date: '1970-01-01'
documents: []
ip: 127.0.0.1
metadata:
sendRef: SENDER-1234
recipients:
- requested_amount: '7040'
requested_currency: NGN
retriable: true
payout_method:
type: NGN::Bank
details:
first_name: Name
last_name: Name
bank_code: 058
bank_account: '123456789'
bank_account_type: '10'
metadata:
sendRef: LOCAL-ID-1234
external_id: 806ec63a-a5a7-43cc-9d75-1ee74fbcc026
FieldDescription:
type: object
properties:
type:
type: string
description: the type of the field.
readOnly: true
example: input
enum:
- input
- select
validations:
$ref: '#/components/schemas/FieldValidation'
Sender:
required:
- city
- country
- documents
- email
- ip
- postal_code
- street
type: object
properties:
id:
type: string
format: uuid
example: bf9ff782-e182-45ac-abea-5bce83ad6670
type:
type: string
description: 'Type of sender to create - either person or business (defaults to person)
'
example: person
enum:
- person
- business
state:
$ref: '#/components/schemas/SenderState'
country:
type: string
description: Country of sender in 2-character alpha ISO 3166-2 country format. This is the residential country for personal senders and the country of incorporation for business senders.
example: NG
street:
type: string
description: Sender's street
example: Fake Street
postal_code:
type: string
description: Zip code of sender
example: '798983'
city:
type: string
description: Sender's city
example: Kampala
phone_country:
type: string
description: Phone country of sender in 2-character alpha ISO 3166-2 country format
example: NG
phone_number:
type: string
description: Phone number of sender (without country callcode)
example: '752403639'
email:
type: string
description: Email of sender
format: email
example: example@home.org
ip:
type: string
description: IP of sender
format: ipv4
example: 127.0.0.1
fingerprint:
type: string
description: Fingerprint of sender
example: fingerprint
address_description:
type: string
description: Description of address
identification_number:
type: string
description: Identification number of document used
example: AB123456
identification_type:
type: string
description: 'Document to be identified. The identification type can be one of the following:
- `DL`: Driving License
- `PP`: International Passport
- `ID`: National ID
- `OT`: Other
Please note for Wizall `XOF::Cash` transactions the valid options are:
- `ID`: National ID
- `PP`: Passport'
example: ID
enum:
- DL
- PP
- ID
- OT
lang:
type: string
description: Determines language of the served content. Defaults to English
example: en
name:
type: string
description: Name of sender (used only with a Business sender)
first_name:
type: string
description: First name of sender (used only with a Personal sender)
example: Johnny
middle_name:
type: string
description: Middle name of sender (used only with a Personal sender)
example: Johnny
last_name:
type: string
description: Last name of sender (used only with a Personal sender)
example: English
birth_date:
type: string
description: Date of birth of sender (used only with a Personal sender)
format: date
occupation:
type: string
description: Occupation of sender (used only with a Personal sender)
example: Accountant
nationality:
type: string
description: The nationality of the sender (used only with a Personal sender)
example: NG
legal_entity_type:
type: string
description: "Legal entity type (used only with a Business sender)\n\nAvailable values:\n - sole_proprietorship: Sole Proprietorship\n - partnership: Partnership\n - privately_owned_company: Privately Owned Company (Limited Company)\n - publicly_owned_company: Publicly Listed Company (PLC)\n - government_owned_entity: Government Owned Entity Trusts\n - trust: Foundations & Similar Entities\n - ngo: Non-Government Organisations / Charities inc Religious bodies and place of worship\n - club_and_society: Clubs and Societies\n - go: GO (Majority Owned Subsidiary of State-Owned Company)\n - financial_institution: Financial Institution\n - mto: Money Transfer Operator (MTO) / Other Licensed Financial Institution\n\nPlease note not all values are acceptable for some our corridors. Please reach out to our sales teams for more information.\n\nNote that if you select `financial_institution` then the fields `vat_registration_number`, `financial_regulator` and `regulatory_licence_number` will be mandatory as well.\n\nNote that if you select `mto` then following fields will be mandatory as well: `vat_registration_number`, `financial_regulator`, `regulatory_licence_number`, `company_office_number`, `company_office_number_country`, `aml_officer_email`, `aml_officer_phone`, `aml_officer_phone_country`, `company_website_url`, `number_of_employees_in_company`, `list_of_countries_of_operation`, `estimated_annual_revenue_turnover`, `declaration`."
example: privately_owned_company
enum:
- sole_proprietorship
- partnership
- privately_owned_company
- publicly_owned_company
- government_owned_entity
- trust
- ngo
- club_and_society
- go
- other
- financial_institution
- mto
registration_date:
type: string
description: The registration date (used only with a Business sender)
format: date
registration_number:
type: string
description: The registration number (used only with a Business sender)
nature_of_business:
type: string
description: "Nature of business options (used only with a Business sender)\n\nAvailable values:\n - personal: Personal\n - agriculture_and_hunting: Agriculture and Hunting\n - forestry: Forestry\n - fishing: Fishing\n - agricultural_by_products: Agricultural By-Products\n - coal_mining: Coal Mining\n - oil_mining: Oil Mining\n - iron_ore_mining: Iron Ore Mining\n - other_metal_and_diamond_mining: Other Metal and Diamond Mining\n - other_mineral_mining: Other Mineral Mining\n - manufacturing_of_food_drink_tobacco: Manufacture of Food/Drink/Tobacco\n - manufacturing_of_textiles_leather_fur_furniture: Manufacture of Textiles/Leather/Fur/Furniture\n - manufacture_of_wooden_products_furniture: Manufacture of Wooden Products/Furniture\n - manufacture_of_paper_pulp_allied_products: Manufacture of Paper/Pulp/Allied Products\n - manufacture_of_chemicals_medical_petroleum_rubber_plastic_products: Manufacture Of Chemicals Medical Petroleum Rubber Plastic Products\n - manufacture_of_pottery_china_glass_stone: Manufacture Of Pottery China Glass Stone\n - manufacture_of_iron_steel_non_ferrous_metals_basic_industries: Manufacture Of Iron Steel Non-Ferrous Metals Basic Industries\n - manufacture_of_metal_products_electrical_and_scientific_engineering: Manufacture Of Metal Products Electrical And Scientific Engineering\n - manufacture_of_jewelry_musical_instruments_toys: Manufacture Of Jewelry Musical Instruments Toys\n - electricity_gas_and_water: Electricity, Gas And Water\n - construction: Construction\n - wholesale_trade: Wholesale Trade\n - retail_trade: Retail Trade\n - catering_incl_hotels: Catering Incl. Hotels\n - transport_storage: Transport Storage\n - communications: Communications\n - finance_and_holding_companies: Finance And Holding Companies\n - insurance: Insurance\n - business_services: Business Services\n - real_estate_development_investment: Real Estate Development Investment\n - central_state_governments: Central State Governments\n - community_services_defence_police_prisons_etc: Community Services Defence Police Prisons Etc\n - social_services_education_health_care: Social Services Education Health Care\n - personal_services_leisure_services: Personal Services - Leisure Services\n - personal_services_domestic_laundry_repairs: Personal Services - Domestic Laundry Repairs\n - personal_services_embassies_international_organisations: Personal Services - Embassies"
enum:
- personal
- agriculture_and_hunting
- forestry
- fishing
- agricultural_by_products
- coal_mining
- oil_mining
- iron_ore_mining
- other_metal_and_diamond_mining
- other_mineral_mining
- manufacturing_of_food_drink_tobacco
- manufacturing_of_textiles_leather_fur_furniture
- manufacture_of_wooden_products_furniture
- manufacture_of_paper_pulp_allied_products
- manufacture_of_chemicals_medical_petroleum_rubber_plastic_products
- manufacture_of_pottery_china_glass_stone
- manufacture_of_iron_steel_non_ferrous_metals_basic_industries
- manufacture_of_metal_products_electrical_and_scientific_engineering
- manufacture_of_jewelry_musical_instruments_toys
- electricity_gas_and_water
- construction
- wholesale_trade
- retail_trade
- catering_incl_hotels
- transport_storage
- communications
- finance_and_holding_companies
- insurance
- business_services
- real_estate_development_investment
- central_state_governments
- community_services_defence_police_prisons_etc
- social_services_education_health_care
- personal_services_leisure_services
- personal_services_domestic_laundry_repairs
- personal_services_embassies_international_organisations
source_of_funds:
type: string
description: The source of funds
custom_source_of_funds:
type: string
description: Custom source of funds
core_business_activity:
type: string
description: The core activity (used only with a Business sender)
purpose_of_opening_account:
type: string
description: The purpose for opening their account (used only with a Business sender)
office_phone:
type: string
description: The official phone number (used only with a Business sender)
vat_registration_number:
type: string
description: The VAT registration number (used only with a Business sender)
financial_regulator:
type: string
description: The Financial Regulator (used only with a Business sender)
regulatory_licence_number:
type: string
description: The Regulatory Licence Number (used only with a Business sender)
contact_person_email:
type: string
description: The contact's email address (used only with a Business sender)
trading_country:
type: string
description: The Business trading country (used only with a Business sender)
trading_address:
type: string
description: The Business trading address (used only with a Business sender)
trading_name:
type: string
description: The Business trading name (used only with a Business sender)
number_monthly_transactions:
type: string
description: The estimated number of monthly transactions (used only with a Business sender)
amount_monthly_transactions:
type: string
description: The estimated amount for all transactions each month in USD (used only with a Business sender)
documents:
type: array
description: "Needed for KYC checks. Required to approve the sender unless KYC is waived for your account.\nPlease send us an empty list of documents: `\"documents\": [ ]` in the request if KYC has been waived.\n\nIf the documents already exist, please send the Document ID eg.\n```JSON\n\"documents\": [\n {\n \"id\": \"b6648ba3-1c7b-4f59-8580-684899c84a07\"\n }\n]\n```"
example:
- id: b6648ba3-1c7b-4f59-8580-684899c84a07
items:
$ref: '#/components/schemas/Document'
metadata:
type: object
description: 'Metadata of sender. You can store any detail specific to your integration here
(for example the local ID of the sender on your end). When requesting sender details you will receive the
sent metadata back. Also when sending sender related webhooks you will receive the details stored here as well.'
example: {}
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
onboarding_status:
type: string
description: The onboarding status of the sender
politically_exposed_people:
type: array
description: "An optional list of politically exposed people, individuals who are or have been entrusted with prominent public functions by a country,\nfor example heads of state or heads of government, senior politicians, senior government, judicial or military officials,\nsenior executives of state owned corporations, important political party officials.\n\nThere is a limit of three (3) politically exposed people per Sender.\n\nPolitically exposed person example:\n```json\n {\n \"politically_exposed_person\": {\n \"name\": \"Ronald Reagan\",\n \"position\": \"President of the United States\",\n \"started_date\": \"1981-01-20T00:00:00.000Z\",\n \"ended_date\": \"1989-01-20T00:00:00.000Z\",\n \"sender_id\": \"344fb668-196d-43db-9d94-b34b7e6c7e0b\"\n }\n }\n```"
example:
- 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
items:
$ref: '#/components/schemas/PoliticallyExposedPerson'
external_id:
type: string
description: 'Optional ID that is supplied by partner linking it to the partner''s own Sender 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
city_of_birth:
type: string
description: City of birth of sender
example: London
country_of_birth:
type: string
description: Country of birth of sender in 2-character alpha ISO 3166-2 country format
example: GB
gender:
type: string
description: 'The gender of the sender:
- `M`: Male
- `F`: Female
- `O`: Other'
example: M
enum:
- M
- F
- O
sales_lead_id:
type: string
description: Sales Lead ID for tracking (optional)
example: HF6HJVF67
created_at:
type: string
description: Date and time of sender was created
readOnly: true
example: 2019-01-11T00:00:00.001+0000
company_office_number:
type: string
description: Phone number of company office (without country callcode, used only with a Business sender)
example: '123123123'
company_office_number_country:
type: string
description: Phone number country of company office in 2-character alpha ISO 3166-2 country format (used only with a Business sender)
example: GB
aml_officer_email:
type: string
description: Email address of AML Officer (used only with a Business sender)
aml_officer_phone:
type: string
description: Phone number of AML Officer (without country callcode, used only with a Business sender)
example: '123123123'
aml_officer_phone_country:
type: string
description: Phone number country of AML Officer in 2-character alpha ISO 3166-2 country format (used only with a Business sender)
example: GB
company_website_url:
type: string
description: Company website URL (used only with a Business sender)
example: www.azafinance.com
number_of_employees_in_company:
type: string
description: Number of employees in company (used only with a Business sender)
example: 250+
list_of_countries_of_operation:
type: array
description: List of countries of operation (used only with a Business sender)
example:
- Spain
- Germany
- Poland
items:
type: string
estimated_annual_revenue_turnover:
type: string
description: Estimated annual turnover (in USD or equivalent, used only with a Business sender)
declaration:
type: string
description: Declaration that the signatory is authorised (used only with a Business sender)
example: 'Yes'
description: "This contains the details of the sender. The first time a specific sender is used the full details should be provided.\nOnce a sender is created and is used, the next time you MUST only send the ID of the sender.\nThis is so we can match the same sender across multiple transactions for KYC and audit purposes.\n\nPersonal Sender Example:\n```json\n{\n // name\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n\n // address\n \"country\": \"US\",\n \"city\": \"New York\",\n \"street\": \"20 W 34th St\",\n \"postal_code\": \"10001\",\n \"address_description\": \"\",\n\n // DOB\n \"birth_date\": \"1974-12-24\",\n\n // Contact Details; You can usually use your company's contact details here\n \"phone_number\": \"+15555551234\",\n \"email\": \"info@transferzero.com\",\n\n // ID of the sender in your system\n \"external_id\": \"Sender:US:234523\",\n\n // these fields are mandatory, but you can usually leave them with the following default values:\n \"documents\": [ ],\n \"ip\": \"127.0.0.1\",\n \"metadata\": {}\n}\n```\n\nBusiness Sender Example:\n\n```json\n{\n \"type\": \"business\",\n \"name\": \"Company name\",\n\n // Country of Incorporation\n \"country\": \"US\",\n\n // Trading address of the company\n \"trading_country\": \"US\",\n \"city\": \"New York\",\n \"street\": \"20 W 34th St\",\n \"postal_code\": \"10001\",\n \"address_description\": \"\",\n\n // Company Details\n \"legal_entity_type\": \"privately_owned_company\",\n \"registration_date\": \"2012-01-25\",\n \"registration_number\": \"VAT1234567\",\n \"nature_of_business\": \"retail_trade\",\n\n // Contact Details\n \"phone_number\": \"+15555551234\",\n \"email\": \"example@home.org\",\n\n // ID of the sender in your system\n \"external_id\": \"Sender:Business:US:234523\",\n\n // these fields are mandatory, but you can usually leave them with the following default values:\n \"documents\": [ ],\n \"ip\": \"127.0.0.1\",\n \"metadata\": {}\n}\n```\n\n[Sender in the API documentation](https://docs.transferzero.com/docs/transaction-flow/#sender)"
example:
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
externalDocs:
description: Sender in the API documentation
url: https://docs.transferzero.com/docs/transaction-flow/#sender
PayoutMethodDetailsEGPBank:
required:
- bank_account
- bank_code
- first_name
- last_name
- street
- transfer_reason
type: object
properties:
first_name:
type: string
middle_name:
type: string
last_name:
type: string
street:
type: string
phone_number:
type: string
bank_account:
type: string
bank_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 \"middle_name\": \"Middle\",\n \"last_name\": \"Last\",\n \"street\": \"1 Main Street\",\n \"phone_number\": \"+201023456789\",\n \"bank_account\": \"1234567890\",\n \"bank_code\": \"0030\",\n \"transfer_reason\": \"personal_account\"\n}\n```\nSee [EGP Bank](https://docs.transferzero.com/docs/payout-details/#egpbank) documentation for the bank_code list"
TransactionResponseExisting:
type: object
properties:
sender:
$ref: '#/components/schemas/Sender'
transaction:
$ref: '#/components/schemas/Transaction'
readOnly: true
FieldSelectValidation:
type: object
properties:
in:
type: object
description: Describes the valid options for this selectbox
readOnly: true
example:
'20': Current
'10': Savings
allow_blank:
type: boolean
description: Describes whether the field is optional or not
readOnly: true
example: false
PayoutMethodDetailsUGXBank:
required:
- bank_account
- branch_code
- city
- first_name
- identity_card_id
- last_name
- postal_code
- street
- transfer_reason
type: object
properties:
first_name:
type: string
last_name:
type: string
street:
type: string
city:
type: string
postal_code:
type: string
identity_card_id:
type: string
bank_account:
type: string
branch_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 \"street\": \"1, Old Taxi Park\",\n \"city\": \"Kampala\",\n \"postal_code\": \"10102\",\n \"identity_card_id\": \"3081900101123411\",\n \"bank_account\": \"1234567890\",\n \"branch_code\": \"130547\",\n \"transfer_reason\": \"personal_account\"\n}\n```\nSee [UGX Bank](https://docs.transferzero.com/docs/payout-details/#ugxbank) documentation for the branch_code list"
PayoutMethod:
type: object
properties:
type:
type: string
description: 'Contains the currency to send the money to, and the type of the money movement
Commonly used payout types are:
- `NGN::Bank` - for Nigerian bank account payments.
- `GHS::Bank` - for Ghanaian bank account payments.
- `GHS::Mobile` - for Ghanaian mobile money payments.
- `UGX::Mobile` - for Ugandan mobile money payments.
- `XOF::Mobile` - for mobile money payments to West-Africa.
- `XOF::Bank` - for Senegalese bank account payments.
- `XOF::Cash` - for Senegalese cash remittance payments.
- `MAD::Cash` - for Moroccan cash remittance payments.
- `EUR::Bank` - for IBAN bank transfers in EUR.
- `GBP::Bank` - for IBAN bank and FP accounts transfers in GBP.
- `ZAR::Bank` - for South Africa bank account payments.
- `USD::Bank` - for USD account payments. *** Currently for Egypt, Nigeria and United States only and in Beta phase ***
- `USD::Cash` - for USD cash remittance payments. *** Currently for Nigeria only and in Beta phase ***
- `KES::Bank` - for Kenyan bank account payments.
- `KES::Mobile` - for Kenyan mobile money payments.
- `XAF::Mobile` - for mobile money payments to Central African (CEMAC) countries. *** Currently in Beta phase ***
- `XAF::Bank` - for Cameroon bank account payments.
- `GNF::Mobile` - for mobile money payments to Guinea.
- `BRL::Bank` - for Brazilian bank account payments.
- `NZD::Bank` - for New Zealand bank account payments.
- `BWP::Bank` - for Botswana bank account payments.
- `ZMW::Bank` - for Zambian bank account payments.
- `CAD::Bank` - for Canadian bank account payments.
- `UGX::Bank` - for Ugandan bank account payments.
- `EGP::Bank` - for Egyptian bank account payments.
- `EGP::Cash` - for Egyptian cash payments.
'
example: NGN::Bank
details:
$ref: '#/components/schemas/PayoutMethodDetails'
metadata:
type: object
description: Metadata of payout method. You can store any kind of information in this field.
example: {}
id:
type: string
format: uuid
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
fields:
type: object
additionalProperties:
$ref: '#/components/schemas/FieldDescription'
description: The fields needed for payments with this payment method with details on validation requirements
readOnly: true
example:
email:
type: input
validations:
inclusion:
in:
NI: National Id
PP: Passport
allow_blank: true
description: This describes the specific details on how the payment has to be routed to the recipient.
example:
metadata: {}
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
type: NGN::Bank
fields:
email:
type: input
validations:
inclusion:
in:
NI: National Id
PP: Passport
allow_blank: true
errors:
phone_number:
- error: invalid
documents:
- error: blank
externalDocs:
description: Payout Types in the API documentation
url: https://docs.transferzero.com/docs/transaction-flow/#payout-type
PaginationMeta:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
readOnly: true
example:
pagination:
next_page: 3
total_count: 45
total_pages: 5
prev_page: 1
current_page: 2
TransactionTraits:
type: object
properties:
auto_refund:
type: boolean
description: Enables or disables the auto refund functionality. Please see [Auto cancellation and refund of transactions](https://docs.transferzero.com/docs/additional-features/#auto-cancellation-and-refund-of-transactions) for more details
account_validation:
type: boolean
description: Enabled or disables the name validation functionality. Please see [Name validation in transactions](https://docs.transferzero.com/docs/additional-features/#name-validation-in-transactions) for more details
description: Additional features that are enabled on the transaction. For more details please see [Additional features](https://docs.transferzero.com/docs/additional-features/) in our API documentation
example:
account_validation: true
auto_refund: true
TransactionState:
type: string
description: 'The state of the transaction, which can be one of the following:
* `initial`: Transaction is created, but not yet ready to receive payments (waiting for Sender to be KYC''d and approved).
* `approved`: Transaction is created and the sender is approved. Payment can be received
* `pending`: There''s an active collection to fund the transaction that needs to clear.
* `received`: Transaction has received the correct payin amount and will start processing the payouts.
* `mispaid`: Transaction received funds, but not the requested amount. The transaction will be resized, and will start payout based on the received funds.
* `manual`: Some of the payments to the recipients have run into issues. Please check the recipient statuses for more information.
* `paid`: Transaction has received correct payins and has performed payouts to all recipients. No further steps required
* `canceled`: The transaction has been cancelled. Transactions are cancelled automatically after one hour if there was no funds received. Once transactions are funded they can be cancelled by the API user unless the recipients have been paid out.
* `refunded`: The transaction has been cancelled after it has been funded, but the funds have been returned now to the sender either partially or fully.
* `processing`: Transaction has received a payin, it''s processing.
* `exception`: An exception happened during the processing of the transaction. Please contact TransferZero'
readOnly: true
example: initial
enum:
- initial
- approved
- pending
- received
- mispaid
- manual
- paid
- canceled
- refunded
- processing
- exception
Recipient:
required:
- payout_method
- requested_amount
- requested_currency
type: object
properties:
requested_amount:
type: number
description: the amount that should be paid to the recipient. This can be in any currency, usually either the input or the output currency. If the value here is not the output currency we will calculate how much the recipient is going to get using the exchange rates active when the transaction was created.
example: 750.0
requested_currency:
type: string
description: the currency of the amount in 3-character alpha ISO 4217 currency format
example: NGN
payout_method:
$ref: '#/components/schemas/PayoutMethod'
metadata:
type: object
description: Additional metadata that can be added to a recipient. These values will be returned on request
example: {}
created_at:
type: string
description: Date and time that the recipient was created.
format: date-time
readOnly: true
editable:
type: boolean
description: Shows whether the recipient can be edited using the PATCH /v1/recipients/{id} endpoint or not
readOnly: true
example: true
retriable:
type: boolean
description: Shows whether the transaction made to the recipient can be retried or not
readOnly: true
example: true
input_usd_amount:
type: number
description: Shows how much this payment is worth in USD
readOnly: true
example: 10
may_cancel:
type: boolean
description: 'If true it shows that the payment can be cancelled immediately using the DELETE /v1/recipients/{id} endpoint.
If false you can still try to cancel it, however it will only gets cancelled once we have confirmation from our partner that the payment has failed.'
readOnly: true
example: true
state_reason:
type: string
description: In case the payment is unsuccessful it holds the error message associated with the last unsuccessful payout.
readOnly: true
state_reason_details:
$ref: '#/components/schemas/RecipientStateReasonDetails'
state:
$ref: '#/components/schemas/RecipientState'
transaction_id:
type: string
description: The ID of the transaction that is related to this recipient
readOnly: true
example: 97e79719-06e4-4794-aeeb-d2d9415d983a
transaction_external_id:
type: string
description: Optional ID that is supplied by partner linking it to the partner's own Transaction ID.
example: 806ec63a-a5a7-43cc-9d75-1ee74fbcc026
transaction_state:
$ref: '#/components/schemas/TransactionState'
exchange_rate:
type: number
description: The exchange rate used in this payment
readOnly: true
example: 1000
fee_fractional:
type: number
description: The fee for this payment in fractional units (for example cents for USD transactions)
readOnly: true
example: 100
input_amount:
type: number
description: The amount that had to be paid in for this payment to proceed
readOnly: true
example: 10
input_currency:
type: string
description: The currency this payment was paid in
readOnly: true
example: USD
output_amount:
type: number
description: The amount that will be paid to the recipient
readOnly: true
example: 10000
output_currency:
type: string
description: The currency the payment will be delivered in
readOnly: true
example: NGN
id:
type: string
format: uuid
readOnly: true
example: 97e79719-06e4-4794-aeeb-d2d9415d983a
type:
type: string
description: 'Type of recipient to create - either person or business (defaults to person)
'
example: person
enum:
- person
- business
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
mandate_id:
type: string
description: 'The ID of the mandate that is related to this recipient.
This field is present when a ZAR bank mandate signing is required or has been completed.'
format: uuid
readOnly: true
example: 97e79719-06e4-4794-aeeb-d2d9415d983a
description: The recipient describes the amount, the currency and the destination where the money should be sent.
example:
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_fractional: 2723
requested_amount: 1000.0
requested_currency: USD
input_amount: 908.0
input_currency: UGX
output_amount: 941.51600841
output_currency: NGN
externalDocs:
description: Recipient documentation
url: https://docs.transferzero.com/docs/transaction-flow/#requested-amount-and-currency
PayinMethodState:
type: string
description: 'The state of the payin method, which can be one of the following:
* `incomplete`: Some fields need to be filled in in_details before we can initiate the collection request.
* `initial`: All required fields in in_details are present and collection process with the sender will start.
* `pending`: Collection process has been started, waiting for sender to send funds.
* `success`: Collection succeeded and funds have been cleared.
* `processing`: Collection succeeded but waiting for funds to fully clear.
* `error`: Collection failed. No funds received from sender. You can update or retry the PayinMethod.
* `mispaid`: Collection succeeded but sender sent the wrong amount.
* `canceled`: The transaction has been canceled and we will refund the sender soon.
* `refunded`: The sender has been refunded the amount they sent in.
* `exception`: An exception happened during processing of the collection. Please contact support.'
readOnly: true
example: initial
enum:
- incomplete
- initial
- pending
- success
- processing
- error
- mispaid
- canceled
- refunded
- exception
PayoutMethodDetailsZMWBank:
required:
- bank_account
- branch_code
- first_name
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
bank_account:
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\": \"1234567890\",\n \"branch_code\": \"ZM210003\",\n}\n```\nSee [ZMW Bank](https://docs.transferzero.com/docs/payout-details/#zmwbank) documentation for the branch_code list"
StateReasonDetails:
type: object
properties:
code:
type: string
description: Status code of transaction
readOnly: true
example: '311'
category:
type: string
description: Main category of status code, it could be paid, unknown, pickupable, temporary_error, recipient_error, sender_error, sender_action_required
readOnly: true
example: temporary_error
messages:
type: array
description: Tiered messages
readOnly: true
example:
- Temporary error
- Switch Error
- Issuer/Switch inoperative
items:
type: string
description:
type: string
description: Public, human readable, detailed error message
readOnly: true
example: The central switch is not accepting transactions at the moment. We will retry the transaction
readOnly: true
example:
code: '311'
category: temporary_error
messages:
- Temporary error - Retriable
- Switch Error
- Issuer/Switch inoperative
description: The central switch is not accepting transactions at the moment. We will retry the transaction
PayoutMethodDetails:
oneOf:
- $ref: '#/components/schemas/PayoutMethodDetailsNGNBank'
- $ref: '#/components/schemas/PayoutMethodDetailsMobile'
- $ref: '#/components/schemas/PayoutMethodDetailsXOFMobile'
- $ref: '#/components/schemas/PayoutMethodDetailsXOFBank'
- $ref: '#/components/schemas/PayoutMethodDetailsXOFCash'
- $ref: '#/components/schemas/PayoutMethodDetailsGHSBank'
- $ref: '#/components/schemas/PayoutMethodDetailsGHSMobile'
- $ref: '#/components/schemas/PayoutMethodDetailsGBPBank'
- $ref: '#/components/schemas/PayoutMethodDetailsIBAN'
- $ref: '#/components/schemas/PayoutMethodDetailsMADCash'
- $ref: '#/components/schemas/PayoutMethodDetailsBalance'
- $ref: '#/components/schemas/PayoutMethodDetailsBTC'
- $ref: '#/components/schemas/PayoutMethodDetailsZARBank'
- $ref: '#/components/schemas/PayoutMethodDetailsUSDBank'
- $ref: '#/components/schemas/PayoutMethodDetailsUSDCash'
- $ref: '#/components/schemas/PayoutMethodDetailsKESMobile'
- $ref: '#/components/schemas/PayoutMethodDetailsKESBank'
- $ref: '#/components/schemas/PayoutMethodDetailsXAFMobile'
- $ref: '#/components/schemas/PayoutMethodDetailsXAFBank'
- $ref: '#/components/schemas/PayoutMethodDetailsGNFMobile'
- $ref: '#/components/schemas/PayoutMethodDetailsBRLBank'
- $ref: '#/components/schemas/PayoutMethodDetailsNZDBank'
- $ref: '#/components/schemas/PayoutMethodDetailsBWPBank'
- $ref: '#/components/schemas/PayoutMethodDetailsZMWBank'
- $ref: '#/components/schemas/PayoutMethodDetailsCADBank'
- $ref: '#/components/schemas/PayoutMethodDetailsUGXBank'
- $ref: '#/components/schemas/PayoutMethodDetailsEGPBank'
- $ref: '#/components/schemas/PayoutMethodDetailsEGPCash'
PoliticallyExposedPerson:
type: object
properties:
id:
type: integer
readOnly: true
example: 1
name:
type: string
description: 'Full name of the politically exposed person
'
example: Ronald Reagan
position:
type: string
description: 'The office held by the politically exposed person
'
example: President of the United States
started_date:
type: string
description: 'The date on which the person started holding the office
'
format: date-time
ended_date:
type: string
description: 'The date on which the person ended holding the office
'
format: date-time
sender_id:
type: string
description: 'The ID of the Sender to whom the person is attached to
'
format: uuid
example: 83a4f5fd-9260-4aaa-9743-63f8a6d8309d
created_at:
type: string
description: Date and time the person was created
format: date-time
readOnly: true
updated_at:
type: string
description: Date and time the person was updated
format: date-time
readOnly: true
PayoutMethodBankAccountTypeEnum:
type: string
description: 'The type of the bank account:
- `10`: Savings account
- `20`: Current account
- `30`: Payment account
- `40`: Salary account'
example: '10'
enum:
- '10'
- '20'
- '30'
- '40'
PayoutMethodDetailsGHSMobile:
required:
- first_name
- last_name
- phone_number
type: object
properties:
first_name:
type: string
last_name:
type: string
phone_number:
type: string
mobile_provider:
$ref: '#/components/schemas/PayoutMethodMobileProviderEnum'
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+233302123456\", // E.164 international format\n \"mobile_provider\": \"vodafone\",\n \"transfer_reason\": \"third_party_person_account\"\n}\n```"
TransactionResponseMeta:
type: object
properties:
existing:
$ref: '#/components/schemas/TransactionResponseExisting'
readOnly: true
PayoutMethodDetailsZARBank:
required:
- bank_account
- first_name
- last_name
- phone_number
type: object
properties:
first_name:
type: string
last_name:
type: string
street:
type: string
postal_code:
type: string
city:
type: string
email:
type: string
bank_code:
type: string
branch_code:
type: string
bank_account:
type: string
phone_number:
type: string
transfer_reason_code:
type: string
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
narration:
type: string
name:
type: string
contact_first_name:
type: string
contact_last_name:
type: string
registration_number:
type: string
nature_of_business:
$ref: '#/components/schemas/PayoutMethodNatureOfBusinessEnum'
legal_entity_type:
$ref: '#/components/schemas/PayoutMethodLegalEntityTypeEnum'
birth_date:
type: string
description: Date of birth of recipient
format: date
description: "```JSON\n \"details\": {\n \"first_name\": \"First\", // Mandatory for personal payouts;\n \"last_name\": \"Last\", // Mandatory for personal payouts;\n \"name\" \"First Ltd\", // Mandatory for business payouts;\n \"contact_first_name\" \"Business\",\n \"contact_last_name\" \"Contact\",\n \"street\": \"Main Street\",\n \"postal_code\": \"AB0001\",\n \"city\": \"Cape Town\",\n \"email\": \"recipient@email.com\",\n \"bank_name\" 'Bank Zero', // Optional\n \"bank_code\": \"334810\", // Optional; Required if branch_code is empty\n \"branch_code\": \"630067\", // Optional; Required if bank_code is empty\n \"bank_account\": \"12345678\",\n \"phone_number\": \"+27119785313\", // E.164 international format\n \"transfer_reason\": \"personal_account\", // New transfer reason field\n \"narration\": \"Birthday Gift\", // Optional\n \"legal_entity_type\": \"sole_proprietorship\", // Optional; Default value is \"person\";\n \"nature_of_business\": \"mining\", // Optional for business payouts;\n \"registration_number\": \"17364BGC\" // Optional for business payouts;\n }\n```\n\nSee [ZAR Bank](https://docs.transferzero.com/docs/payout-details/#zarbank) documentation for the bank_code and transfer_reason lists"
PayoutMethodDetailsUSDCash:
required:
- country
- first_name
- last_name
- phone_number
type: object
properties:
first_name:
type: string
last_name:
type: string
phone_number:
type: string
country:
$ref: '#/components/schemas/PayoutMethodCountryEnum'
birth_date:
type: string
description: Date of birth of recipient
format: date
description: "```JSON\n \"details\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"phone_number\": \"+2341234567\", // E.164 international format\n \"country\": \"NG\"\n }\n```\nSee [USD Cash](https://docs.transferzero.com/docs/payout-details/#usdcash) documentation for the country list"
PayinMethodDetailsBTC:
type: object
properties:
refund_address:
type: string
description: Please make sure the refund_address is a valid BTC address belonging to the sender, as that is going to be used in case the transaction has to be refunded.
description: "```JSON\n \"details\": {\n \"refund_address\": \"n4VQ5YdHf7hLQ2gWQYYrcxoE5B7nWuDFNF\"\n }\n```"
Pagination:
type: object
properties:
current_page:
type: integer
description: The number of the current page
readOnly: true
example: 2
next_page:
type: integer
description: The number of the next page. If no next page exists, this will be `null`
readOnly: true
example: 3
prev_page:
type: integer
description: The number of the previous page. If no previous page exists, this will be `null`
readOnly: true
example: 1
total_pages:
type: integer
description: The number of pages in the result set
readOnly: true
example: 5
total_count:
type: integer
description: The total number of results in the set
readOnly: true
example: 45
readOnly: true
example:
next_page: 3
total_count: 45
total_pages: 5
prev_page: 1
current_page: 2
PayinMethodUxFlow:
type: string
description: 'Describes the collection experience that will be presented to
the sender. Can be one of the following:
* `ussd_popup`: Payment prompt is pushed to the sender''s phone. They can approve or decline. Supported for GHS::Mobile, UGX::Mobile
* `ussd_voucher`: Sender has to request an authorization code via ussd of the mobile provider and then provide that code to initiate the transaction. Supported for XOF::Mobile(Orange)
* `ussd_menu_approval`: Sender has to dial a USSD code and navigate to a list of payments to approve.
* `otp_verified_ussd_popup`: Sender receives and validates an OTP then a payment prompt is pushed if the OTP they submit is valid.
* `bank_transfer`: For bank collections. Sender should send funds to the bank account details specified in out_details. Supported for EUR::Bank, GBP::Bank
* `http_redirect`: The sender will be redirected to a website where they can fill in their details to initiate the collection.'
example: ussd_popup
enum:
- ussd_popup
- ussd_voucher
- ussd_menu_approval
- otp_verified_ussd_popup
- bank_transfer
- http_redirect
- blockchain
- unknown
TransactionListResponse:
type: object
properties:
object:
type: array
readOnly: true
items:
$ref: '#/components/schemas/Transaction'
meta:
$ref: '#/components/schemas/PaginationMeta'
readOnly: true
example:
meta:
pagination:
next_page: 3
total_count: 45
total_pages: 5
prev_page: 1
current_page: 2
object:
- 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_fractional: 2723
requested_amount: 1000.0
requested_currency: USD
input_amount: 908.0
input_currency: UGX
output_amount: 941.51600841
output_currency: NGN
- 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_fractional: 2723
requested_amount: 1000.0
requested_currency: USD
input_amount: 908.0
input_currency: UGX
output_amount: 941.51600841
output_currency: NGN
paid_amount: 1000
state: initial
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
input_currency: NGN
errors:
phone_number:
- error: invalid
documents:
- error: blank
- 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_fractional: 2723
requested_amount: 1000.0
requested_currency: USD
input_amount: 908.0
input_currency: UGX
output_amount: 941.51600841
output_currency: NGN
- 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_fractional: 2723
requested_amount: 1000.0
requested_currency: USD
input_amount: 908.0
input_currency: UGX
output_amount: 941.51600841
output_currency: NGN
paid_amount: 1000
state: initial
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
input_currency: NGN
errors:
phone_number:
- error: invalid
documents:
- error: blank
PayoutMethodPixKeyTypeEnum:
type: string
description: 'The type of pix key used by the recipient
- `cpf`: Natural person register number
- `cnpj`: Company registration number
- `phone`: Phone number
- `email`: Email address
- `evp`: Virtual payment address'
example: email
enum:
- cpf
- cnpj
- phone
- email
- evp
PayoutMethodDetailsNZDBank:
required:
- bank_account
- bank_name
- first_name
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
bank_account:
type: string
bank_name:
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\": \"1212341234567123\",\n \"bank_name\": \"ASB Bank\"\n}\n```\n\nSee [NZD Bank](https://docs.transferzero.com/docs/payout-details/#nzdbank) documentation for the bank_name list"
PayoutMethodDetailsXAFMobile:
required:
- first_name
- last_name
- mobile_provider
- phone_number
type: object
properties:
first_name:
type: string
last_name:
type: string
phone_number:
type: string
mobile_provider:
$ref: '#/components/schemas/PayoutMethodMobileProviderEnum'
country:
$ref: '#/components/schemas/PayoutMethodCountryEnum'
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\": \"+237674044436\", // E.164 international format\n \"mobile_provider\": \"orange\",\n \"country\": \"CM\"\n}\n```"
PayoutMethodGenderEnum:
type: string
description: 'The gender of the sender:
- `M`: Male
- `F`: Female'
example: F
enum:
- M
- F
PayoutMethodDetailsMobile:
required:
- first_name
- last_name
- phone_number
type: object
properties:
first_name:
type: string
last_name:
type: string
phone_number:
type: string
mobile_provider:
$ref: '#/components/schemas/PayoutMethodMobileProviderEnum'
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\": \"+221708766123\" // E.164 international format\n}\n```\n\nPlease note when sending XOF::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```"
PayoutMethodDetailsIBAN:
required:
- first_name
- iban
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
iban:
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\": \"DE89370400440532013000\",\n \"bic\": \"DEUTDEBBXXX\", // Optional\n \"bank_name\": \"Deutsche Bank\", // Optional\n \"narration\": \"Birthday Gift\" // Optional\n}\n```"
TransactionResponse:
type: object
properties:
object:
$ref: '#/components/schemas/Transaction'
meta:
$ref: '#/components/schemas/TransactionResponseMeta'
readOnly: true
example:
object:
id: 5280d11f-0ed3-4a60-ab07-29fdb058e4c4
metadata: {}
state: approved
input_amount: 1000.0
input_currency: GBP
sender:
id: fdee3b02-81ad-409d-9f34-2b0dd5c39e8f
type: person
state: approved
country: UG
street: fake street
postal_code: fak3 one
city: London
phone_number: '+256752403639'
email: example@home.org
ip: 127.0.0.1
first_name: Peter
last_name: Smith
birth_date: '1987-08-08'
metadata:
my: data
providers: {}
payin_methods: []
paid_amount: 0.0
due_amount: 1000.0
recipients:
- id: 31288256-ec72-4a0a-bab7-06fb3a6cc8dd
transaction_id: 5280d11f-0ed3-4a60-ab07-29fdb058e4c4
created_at: '2017-08-08T13:19:32.855Z'
input_usd_amount: 772.5
state: initial
transaction_state: initial
editable: true
retriable: true
may_cancel: true
requested_amount: 750.0
requested_currency: USD
input_amount: 1000.0
input_currency: EUR
output_amount: 294750.0
output_currency: NGN
payout_method:
id: e7e6ca2e-1b38-4d55-991c-d6933c2f6043
type: NGN::Bank
details:
first_name: Johnny
last_name: English
bank_code: '050'
bank_account: '11039382982833'
bank_account_type: '20'
metadata: {}
metadata: {}
created_at: 2017-08-08 13:19:32 UTC
expires_at: '2017-08-08T14:19:32.855Z'
external_id: 806ec63a-a5a7-43cc-9d75-1ee74fbcc026
meta:
existing:
sender:
id: fdee3b02-81ad-409d-9f34-2b0dd5c39e8f
type: person
state: approved
country: UG
street: fake street
postal_code: fak3 one
city: London
phone_number: '+256752403639'
email: example@home.org
ip: 127.0.0.1
first_name: Peter
last_name: Smith
birth_date: '1987-08-08'
metadata:
my: data
providers: {}
transaction:
id: 5280d11f-0ed3-4a60-ab07-29fdb058e4c4
metadata: {}
state: approved
input_amount: 1000.0
input_currency: GBP
sender:
id: fdee3b02-81ad-409d-9f34-2b0dd5c39e8f
type: person
state: approved
country: UG
street: fake street
postal_code: fak3 one
city: London
phone_number: '+256752403639'
email: example@home.org
ip: 127.0.0.1
first_name: Peter
last_name: Smith
birth_date: '1987-08-08'
metadata:
my: data
providers: {}
payin_methods: []
paid_amount: 0.0
due_amount: 1000.0
recipients:
- id: 31288256-ec72-4a0a-bab7-06fb3a6cc8dd
transaction_id: 5280d11f-0ed3-4a60-ab07-29fdb058e4c4
created_at: '2017-08-08T13:19:32.855Z'
input_usd_amount: 772.5
state: initial
transaction_state: initial
editable: true
retriable: true
may_cancel: true
requested_amount: 750.0
requested_currency: USD
input_amount: 1000.0
input_currency: EUR
output_amount: 294750.0
output_currency: NGN
payout_method:
id: e7e6ca2e-1b38-4d55-991c-d6933c2f6043
type: NGN::Bank
details:
first_name: Johnny
last_name: English
bank_code: '050'
bank_account: '11039382982833'
bank_account_type: '20'
metadata: {}
metadata: {}
created_at: 2017-08-08 13:19:32 UTC
expires_at: '2017-08-08T14:19:32.855Z'
external_id: 806ec63a-a5a7-43cc-9d75-1ee74fbcc026
ErrorStatus:
type: object
properties:
status:
type: integer
readOnly: true
error:
type: string
readOnly: true
readOnly: true
PayoutMethodCashProviderEnum:
type: string
description: 'The cash provider for the pickup:
For XOF valid options are:
- `wizall`: Wizall'
example: wizall
enum:
- wari
- wizall
PayoutMethodMobileProviderEnum:
type: string
description: 'The Mobile Wallet provider of the recipient:
For XOF (Senegal) valid options are:
- `orange`: Orange
- `tigo`: Tigo
- `emoney`: Emoney
- `free`: Free
- `expresso` : Expresso
- `wave`: Wave
For XOF (Ivory Coast) valid options are:
- `orange`: Orange
- `moov`: Moov
- `mtn`: MTN
- `wave`: Wave
For XOF (Burkina Faso) valid options are:
- `orange`: Orange
- `mobicash`: Mobicash
- `moov` : Moov
For XOF (Togo) valid options are:
- `moov`: Moov
- `tmoney`: Tmoney
For XOF (Benin) valid options are:
- `moov`: Moov
- `mtn`: Mtn
For XOF (Mali) valid options are:
- `orange`: Orange
- `mobicash`: Mobicash
- `tigo` : Tigo
For GHS valid options are:
- `airteltigo`: AirtelTigo
- `mtn`: MTN
- `vodafone`: Vodafone
For KES valid options are:
- `mpesa`: MPESA
For UGX valid options are:
- `africell`: Africell
- `airtel`: Airtel
- `mtn`: MTN
- `telecom`: Telecom
For XAF (Chad) valid options are:
- `moov`: Moov
For XAF (Cameroon) valid options are:
- `orange`: Orange
- `mtn`: MTN
For XAF (Congo) valid options are:
- `airtel`: Airtel
- `mtn`: MTN
For XAF (Gabon) valid options are:
- `airtel`: Airtel
- `moov`: Moov
For GNF (Guinea) valid options are:
- `orange`: Orange
- `mtn`: MTN'
example: orange
enum:
- africell
- airtel
- airteltigo
- emoney
- expresso
- free
- mobicash
- moov
- mpesa
- mtn
- orange
- telecom
- tigo
- tmoney
- vodafone
- wave
PayoutMethodNatureOfBusinessEnum:
type: string
description: "Nature of business options (used only with a Business sender)\n\nAvailable values:\n - personal: Personal\n - agriculture_and_hunting: Agriculture and Hunting\n - forestry: Forestry\n - fishing: Fishing\n - agricultural_by_products: Agricultural By-Products\n - coal_mining: Coal Mining\n - oil_mining: Oil Mining\n - iron_ore_mining: Iron Ore Mining\n - other_metal_and_diamond_mining: Other Metal and Diamond Mining\n - other_mineral_mining: Other Mineral Mining\n - manufacturing_of_food_drink_tobacco: Manufacture of Food/Drink/Tobacco\n - manufacturing_of_textiles_leather_fur_furniture: Manufacture of Textiles/Leather/Fur/Furniture\n - manufacture_of_wooden_products_furniture: Manufacture of Wooden Products/Furniture\n - manufacture_of_paper_pulp_allied_products: Manufacture of Paper/Pulp/Allied Products\n - manufacture_of_chemicals_medical_petroleum_rubber_plastic_products: Manufacture Of Chemicals Medical Petroleum Rubber Plastic Products\n - manufacture_of_pottery_china_glass_stone: Manufacture Of Pottery China Glass Stone\n - manufacture_of_iron_steel_non_ferrous_metals_basic_industries: Manufacture Of Iron Steel Non-Ferrous Metals Basic Industries\n - manufacture_of_metal_products_electrical_and_scientific_engineering: Manufacture Of Metal Products Electrical And Scientific Engineering\n - manufacture_of_jewelry_musical_instruments_toys: Manufacture Of Jewelry Musical Instruments Toys\n - electricity_gas_and_water: Electricity, Gas And Water\n - construction: Construction\n - wholesale_trade: Wholesale Trade\n - retail_trade: Retail Trade\n - catering_incl_hotels: Catering Incl. Hotels\n - transport_storage: Transport Storage\n - communications: Communications\n - finance_and_holding_companies: Finance And Holding Companies\n - insurance: Insurance\n - business_services: Business Services\n - real_estate_development_investment: Real Estate Development Investment\n - central_state_governments: Central State Governments\n - community_services_defence_police_prisons_etc: Community Services Defence Police Prisons Etc\n - social_services_education_health_care: Social Services Education Health Care\n - personal_services_leisure_services: Personal Services - Leisure Services\n - personal_services_domestic_laundry_repairs: Personal Services - Domestic Laundry Repairs\n - personal_services_embassies_international_organisations: Personal Services - Embassies"
example: personal
enum:
- personal
- agriculture_and_hunting
- forestry
- fishing
- agricultural_by_products
- coal_mining
- oil_mining
- iron_ore_mining
- other_metal_and_diamond_mining
- other_mineral_mining
- manufacturing_of_food_drink_tobacco
- manufacturing_of_textiles_leather_fur_furniture
- manufacture_of_wooden_products_furniture
- manufacture_of_paper_pulp_allied_products
- manufacture_of_chemicals_medical_petroleum_rubber_plastic_products
- manufacture_of_pottery_china_glass_stone
- manufacture_of_iron_steel_non_ferrous_metals_basic_industries
- manufacture_of_metal_products_electrical_and_scientific_engineering
- manufacture_of_jewelry_musical_instruments_toys
- electricity_gas_and_water
- construction
- wholesale_trade
- retail_trade
- catering_incl_hotels
- transport_storage
- communications
- finance_and_holding_companies
- insurance
- business_services
- real_estate_development_investment
- central_state_governments
- community_services_defence_police_prisons_etc
- social_services_education_health_care
- personal_services_leisure_services
- personal_services_domestic_laundry_repairs
- personal_services_embassies_international_organisations
PayoutMethodDetailsKESBank:
required:
- bank_account
- bank_code
- first_name
- identity_card_id
- identity_card_type
- last_name
- street
- transfer_reason
type: object
properties:
first_name:
type: string
last_name:
type: string
street:
type: string
city:
type: string
bank_code:
type: string
bank_account:
type: string
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
identity_card_type:
$ref: '#/components/schemas/PayoutMethodIdentityCardTypeEnum'
identity_card_id:
type: string
relationship_to_sender:
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 \"street\": \"Main Street\",\n \"city\": \"Nairobi\",\n \"bank_code\": \"68\",\n \"bank_account\": \"12345678\",\n \"transfer_reason\": \"personal_account\", // New transfer reason field\n \"identity_card_type\": \"ID\", // refers to the recipient's ID details; Values: \"PP\": Passport, \"ID\": National ID or \"O\": Other\n \"identity_card_id\": \"AB12345678\", // refers to the recipient's ID details\n \"relationship_to_sender\": \"Relative\" // Optional\n }\n```\n\nSee [KES Bank](https://docs.transferzero.com/docs/payout-details/#kesbank) documentation for the `bank_code` and `transfer_reason` lists"
PayoutMethodDetailsEGPCash:
required:
- first_name
- last_name
- middle_name
- phone_number
- street
- transfer_reason
type: object
properties:
first_name:
type: string
middle_name:
type: string
last_name:
type: string
phone_number:
type: string
street:
type: string
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
email:
type: string
reference:
type: string
description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"middle_name\": \"Middle\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+201023456789\",\n \"street\": \"1 Main Street\",\n \"transfer_reason\": \"personal_account\",\n \"email\": \"recipient@email.com\", // Optional\n \"reference\": \"3414006608\" // Optional reference that'll appear on the recipient pickup notification (if provided must be unique and exactly 10 digits long)\n}"
PayoutMethodDetailsXOFCash:
required:
- cash_provider
- first_name
- last_name
- phone_number
type: object
properties:
first_name:
type: string
last_name:
type: string
phone_number:
type: string
cash_provider:
$ref: '#/components/schemas/PayoutMethodCashProviderEnum'
country:
$ref: '#/components/schemas/PayoutMethodCountryEnum'
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\": \"+221774044436\", // E.164 international format\n \"cash_provider\": \"wizall\" // Mandatory; Values: \"wizall\";\n \"country\": \"SN\" // Optional; Values: \"CI\", \"ML\" or \"SN\"; Default value is \"SN\";\n}\n```\n\nPlease note all senders trying to create Wizall cash pickup requests must have `identity_type` and `identity_number` present. The fields above are generally considered optional for senders for other payment corridors. If you wish to use an existing sender who has some of these fields missing you can provide them alongside the `id` or `external_id` field in the sender details.\nFor example -\n\n```JSON\n{\n \"transaction\": {\n \"sender\": {\n \"external_id\": \"\",\n \"identity_type\": \"ID\",\n \"identity_number\": \"AB12345678\",\n (...)\n },\n (...)\n }\n}\n```"
PayoutMethodIdentityCardTypeEnum:
type: string
description: 'The type of the identity card used by the sender or recipient:
- `PP`: Passport
- `ID`: National Identity Card
- `O`: Other type of identity card
- `DL`: Driving License
- `OT`: Other type of identity card'
example: PP
enum:
- O
- PP
- ID
- DL
- OT
ValidationErrorDescription:
type: object
properties:
error:
type: string
description: Describes what the problem is with the field
readOnly: true
example: invalid
description: The description of the error
readOnly: true
example:
error: invalid
PayoutMethodDetailsUSDBank:
required:
- country
- first_name
- last_name
type: object
properties:
first_name:
type: string
middle_name:
type: string
last_name:
type: string
phone_number:
type: string
bank_code:
type: string
bank_account:
type: string
bank_account_type:
$ref: '#/components/schemas/PayoutMethodBankAccountTypeEnum'
bank_name:
type: string
routing_number:
type: string
swift_code:
type: string
iban:
type: string
street:
type: string
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
country:
$ref: '#/components/schemas/PayoutMethodCountryEnum'
birth_date:
type: string
description: Date of birth of recipient
format: date
description: "Nigeria:\n```JSON\n \"details\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"phone_number\": \"+2341234567\", // E.164 international format\n \"bank_code\": \"057\",\n \"bank_account\": \"1234567890\",\n \"country\": \"NG\"\n }\n```\nSee [USD Bank](https://docs.transferzero.com/docs/payout-details/#usdbank) documentation for the bank_code and country lists\n\nUnited States:\n```JSON\n \"details\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"bank_account\": \"1234567890\",\n \"bank_account_type\": \"20\", // 10 for Savings, 20 for Checking\n \"bank_name\": \"US Bank\",\n \"routing_number\": \"091000022\",\n \"swift_code\": \"USBKUS44IMT\",\n \"country\": \"US\"\n }\nSee [USD Bank](https://docs.transferzero.com/docs/payout-details/#usdbank-1) documentation\n\nEgypt:\n```JSON\n \"details\": {\n \"first_name\": \"Jane\",\n \"middle_name\": \"Jill\", // optional\n \"last_name\": \"Doe\",\n \"street\": \"1 Main Street\",\n \"phone_number\": \"+201023456789\",\n \"iban\": \"EG380019000500000000263180002\",\n \"transfer_reason\": \"personal_account\",\n }\n```\nSee [USD Bank](https://docs.transferzero.com/docs/payout-details/#usdbank-2) documentation"
SenderState:
type: string
description: 'The state of the sender. Can be one of the following:
- `incomplete`: When a sender has not submitted required details or documents (cannot transact)
- `initial`: When a sender is created and has not been through any KYC checking (cannot transact)
- `verified`: A sender has passed sanction list checks (cannot transact)
- `approved`: The sender has passed both KYC and sanction checks (can transact)
- `banned`: An admin has banned the sender (cannot transact)
- `rejected`: The sender has failed sanction list checks (cannot transact)
- `disabled`: A sender is put into this state as a result of a delete request via the API (cannot transact)'
readOnly: true
example: initial
enum:
- incomplete
- initial
- verified
- approved
- banned
- rejected
- disabled
PayinMethodDetailsNGNBank:
type: object
properties:
phone_number:
type: string
description: Sender's phone number
example: '+2348187221236'
account_name:
type: string
description: Merchant's virtual account name
example: Test Merchant
account_number:
type: string
description: Merchant's virtual account number
example: '1234567890'
description: "```JSON\n \"details\": {\n \"phone_number\": \"+2348187221236\",\n \"account_name\": \"Test Merchant\",\n \"account_number\": \"1234567890\"\n }\n```"
PayoutMethodLegalEntityTypeEnum:
type: string
description: 'The entity type of the recipient.
For ZAR personal payouts valid options are:
- `person`: Person
For ZAR business payouts valid options are:
- `sole_proprietorship`: Sole Proprietorship
- `privately_owned_company`: Privately Owned Company (Limited Company)
- `publicly_owned_company`: Publicly Owned Company (PLC)
- `government_owned_entity`: Government Owned Entity Trusts
- `partnership`: Partnership
- `go`: GO (Majority Owned Subsidiary of State-Owned Company)
- `financial_institution`: Financial Institution'
example: person
enum:
- person
- sole_proprietorship
- privately_owned_company
- publicly_owned_company
- government_owned_entity
- partnership
- go
- financial_institution
PayoutMethodTransferReasonEnum:
type: string
description: "Reason of transfer\n\nAvailable values:\n - `personal_account`: Sending money into my own account\n - `donations_and_gifts`: Donations and gifts\n - `third_party_person_account`: Sending money to a friend, family member or any third party person\n - `mortgage_repayments`: Mortgage repayments\n - `business_travel_payments`: Business Travel Payments\n - `personal_travel_payments`: Personal Travel Payments\n - `tuition_fees`: Tuition fees\n - `financial_commission_fees`: Commission and fees for financial services\n - `financial_services_proceeds`: Proceeds for financial services charged for advice provided\n - `individual_property_investments`: Investment into property by a foreign individual\n - `other_investments`: Investment by a foreign individual - other\n - `corporate_property_investments`: Investment into property by a foreign corporate entity\n - `immigrants_capital_payments`: Capital payments by immigrants\n - `legal_services`: Legal services\n - `accounting_services`: Accounting services\n - `consulting_services`: Management consulting services\n - `public_relation_services`: Public relation services\n - `ads_and_market_research_services`: Advertising & market research services\n - `managerial_services`: Managerial services\n - `medical_and_dental_services`: Medical and dental services\n - `educational_services`: Educational services\n - `operational_leasing`: Operational leasing\n - `cultural_and_recreational_services`: Cultural and recreational services\n - `salary_resident_out_country`: Salary paid to South African Resident Temporarily Abroad\n - `salary_non_resident_in_country`: Salary paid to a non-resident employee in South Africa\n - `salary_contract_worker_in_country`: Salary paid to a foreign national contract worker in South Africa\n - `social_security_schemes`: Payments to social security schemes\n - `charities_and_religious_bodies`: Payments to charities and religious bodies\n - `donations_and_aid_to_government`: Donations and aid to Government\n - `donations_and_aid_to_private`: Donations and aid to private sector\n - `pensions`: Pensions\n - `annuities`: Annuities\n - `inheritances`: Inheritances\n - `alimony`: Alimony\n - `tax_income`: Tax - Income tax\n - `tax_vat_refunds`: Tax - VAT refunds\n - `tax_other`: Tax - Other\n - `non_life_insurance_premiums`: Insurance premiums (non life/short term)\n - `life_insurance_premiums`: Insurance premiums (life)\n - `dividends`: Dividends\n - `branch_profits`: Branch profits\n - `commision_or_brokerage`: Commission or brokerage\n - `rental`: Rental\n - `individual_investment_income_from_abroad`: Income earned abroad by a resident on an individual investment\n - `shares_sale`: Sale of shares\n - `bonds_sale`: Sale of bonds\n - `money_market_instruments_sale`: Sale of money market instruments\n - `funds_repatriation_of_foreign_bank_account`: Repatriation of funds out of a foreign bank account\n - `mutual_funds_sale_or_collective_investment`: Sale of mutual funds or collective investment schemes\n - `overseas_property_sale`: Sale of overseas property\n - `sale_and_repatriation_of_other_investment`: Sale and repatriation of other investment\n - `repatriation_south_african_reserve_bank_instruction`: Repatriation on instruction by the South African Reserve Bank\n - `resident_loan_from_non_resident_share_holder`: Loan made to a resident by a non-resident shareholder\n - `resident_loan_from_non_resident_third_party`: Loan made to a resident by a non-resident third party\n - `resident_loan_repayment_from_overseas_living_south_african`: Repayment by a South African living overseas of a loan granted by a resident\n - `study_loan_repayment`: Repayment of a study loan\n - `shareholders_loan_repayment`: Repayment of a shareholders loan\n - `third_party_loan_repayment`: Repayment of a third party loan (excluding shareholders)\n - `trade_finance_loan_repayment`: Repayment of a trade finance loan\n - `research_and_development_proceeds`: Proceeds received for research and development services\n - `research_and_development_funding`: Funding received for research and development\n - `machinary_and_equipment_repairs`: Repairs and maintenance on machinery and equipment\n - `architectural_engineering_technical_services`: Architectural, engineering and other technical services\n - `agrigultural_mining_waste_depollution_services`: Agricultural, mining, waste treatment and depollution services\n - `construction_services`: Proceeds for construction services\n - `telecommunication_services`: Payments for telecommunication services\n - `data_news_agency_fees`: Payments for data, news related and news agency fees\n - `road_passenger_services`: Payments for passenger services - road\n - `rail_passenger_services`: Payments for passenger services - rail\n - `sea_passenger_services`: Payments for passenger services - sea\n - `air_passenger_services`: Payments for passenger services - air\n - `road_freight_services`: Payments for freight services - road\n - `rail_freight_services`: Payments for freight services - rail\n - `sea_freight_services`: Payments for freight services - sea\n - `air_freight_services`: Payments for freight services - air\n - `road_postal_and_courier_services`: Payments for postal and courier services - road\n - `rail_postal_and_courier_services`: Payments for postal and courier services - rail\n - `sea_postal_and_courier_services`: Payments for postal and courier services - sea\n - `air_postal_and_courier_services`: Payments for postal and courier services - air\n - `listed_shares_investment`: Investment in listed shares\n - `non_listed_shares_investment`: Investment in non-listed shares\n - `money_market_instruments_investment`: Investment into money market instruments\n - `listed_bonds_investment`: Investment into listed bonds\n - `non_listed_bonds_investment`: Investment into non-listed bonds\n - `reproduce_distribute_rights_license`: Rights assigned for licences to reproduce and/or distribute\n - `patents_and_investions_rights_license`: Rights assigned for using patents and inventions (licensing)\n - `patterns_and_designs_rights`: Rights assigned for using patterns and designs (including industrial processes)\n - `copyrights_rights`: Rights assigned for using copyrights\n - `franchises_and_trademarks_rights`: Rights assigned for using franchises and trademarks\n - `patents_and_inventions_disposal`: Disposal of patents and inventions\n - `patterns_and_designs_disposal`: Disposal of patterns and designs (including industrial processes)\n - `copyrights_disposal`: Disposal of copyrights\n - `franchises_and_trademarks_disposal`: Disposal of franchises and trademarks\n - `sales_of_manuscripts_sound_recordings_films`: Sales of original manuscripts, sound recordings and films\n - `funds_related_to_recording_productions`: Receipt of funds relating to the production of motion pictures, radio and television programs and musical recordings\n - `software_ownership_rights_sale`: The outright selling of ownership rights of software\n - `computer_services`: Computer-related services including maintenance, repair and consultancy\n - `customised_software_sales`: Commercial sales of customised software and related licenses for use of customers\n - `non_customised_software_on_physical_media_periodic_licence_sale`: Commercial sales of non-customised software on physical media with periodic licence to use\n - `non_customised_software_on_pyisical_media_perpetual_use_sale`: Commercial sales of non-customised software provided on physical media with right to perpetual (ongoing) use\n - `non_customised_software_for_downloading_electronically_made_periodic_licence_sale`: Commercial sales of non-customised software provided for downloading or electronically made available with periodic license\n - `non_customised_software_for_downloading_electronically_made_single_payment_sale`: Commercial sales of non-customised software provided for downloading or electronically made available with single payment\n - `fixed_assets_donations_to_sa_government`: Donations to SA Government for fixed assets\n - `fixed_assets_donations_to_corporate_entities`: Donations to corporate entities - fixed assets\n - `property_disinvestment_by_corporate_entity_resident`: Disinvestment of property by a resident corporate entity\n - `other_business_services`: Proceeds for other business services not included elsewhere\n - `institutional_investor_disinvestment`: Disinvestment by resident institutional investor - Collective Investment Scheme\n - `government_services`: Payment for Government Services\n\n### ZAR Bidvest mandate-bypass-eligible keys\n\nThe following short-form values opt a ZAR Bidvest payout into the SARB FinSurv §B.1 mandate-bypass flow (no signed mandate required) when ALL of these conditions hold:\n\n - the payout is on the ZAR Bidvest corridor (not `access_bank`),\n - the recipient is a natural person (`first_name` populated),\n - the requested currency is ZAR,\n - the output amount is ≤ R50,000.\n\nIf any condition is not met, the transaction falls back to the standard mandate-signing flow. Sending any of these keys is therefore safe even when bypass is not active — the value is recorded against the transfer regardless.\n\n - `own_account`: Sending money into my own account\n - `donations_gifts`: Donations and gifts\n - `family_support`: Sending money to a friend, family member or any third party person\n - `mortgage_repayment`: Mortgage repayments\n - `business_travel`: Business Travel Payments\n - `personal_travel`: Personal Travel Payments\n - `tuition_fees`: Tuition fees (also a general-purpose key)\n - `legal_services`: Legal services (also a general-purpose key)\n - `accounting_services`: Accounting services (also a general-purpose key)\n - `management_consulting`: Management consulting services\n - `advertising_market_research`: Advertising and market research services\n - `cultural_recreational`: Cultural and recreational services\n - `salary_resident_abroad`: Salary — SA resident temporarily abroad\n - `salary_non_resident_in_sa`: Salary — non-resident employee in SA\n - `salary_foreign_contract_in_sa`: Salary — foreign contract worker in SA\n - `pensions`: Pensions (also a general-purpose key)\n - `annuities`: Annuities (also a general-purpose key)\n - `inheritances`: Inheritances (also a general-purpose key)\n - `alimony`: Alimony (also a general-purpose key)\n - `dividends`: Dividends (also a general-purpose key)\n - `commission_brokerage`: Commission or brokerage\n - `rental`: Rental (also a general-purpose key)\n - `investment_income`: Income earned abroad on individual investment\n - `architectural_engineering`: Architectural / engineering / technical services\n - `computer_services`: Computer-related services (also a general-purpose key)"
example: personal_account
enum:
- personal_account
- donations_and_gifts
- third_party_person_account
- mortgage_repayments
- business_travel_payments
- personal_travel_payments
- tuition_fees
- financial_commission_fees
- financial_services_proceeds
- individual_property_investments
- other_investments
- corporate_property_investments
- immigrants_capital_payments
- legal_services
- accounting_services
- consulting_services
- public_relation_services
- ads_and_market_research_services
- managerial_services
- medical_and_dental_services
- educational_services
- operational_leasing
- cultural_and_recreational_services
- salary_resident_out_country
- salary_non_resident_in_country
- salary_contract_worker_in_country
- social_security_schemes
- charities_and_religious_bodies
- donations_and_aid_to_government
- donations_and_aid_to_private
- pensions
- annuities
- inheritances
- alimony
- tax_income
- tax_vat_refunds
- tax_other
- non_life_insurance_premiums
- life_insurance_premiums
- dividends
- branch_profits
- commision_or_brokerage
- rental
- individual_investment_income_from_abroad
- shares_sale
- bonds_sale
- money_market_instruments_sale
- funds_repatriation_of_foreign_bank_account
- mutual_funds_sale_or_collective_investment
- overseas_property_sale
- sale_and_repatriation_of_other_investment
- repatriation_south_african_reserve_bank_instruction
- resident_loan_from_non_resident_share_holder
- resident_loan_from_non_resident_third_party
- resident_loan_repayment_from_overseas_living_south_african
- study_loan_repayment
- shareholders_loan_repayment
- third_party_loan_repayment
- trade_finance_loan_repayment
- research_and_development_proceeds
- research_and_development_funding
- machinary_and_equipment_repairs
- architectural_engineering_technical_services
- agrigultural_mining_waste_depollution_services
- construction_services
- telecommunication_services
- data_news_agency_fees
- road_passenger_services
- rail_passenger_services
- sea_passenger_services
- air_passenger_services
- road_freight_services
- rail_freight_services
- sea_freight_services
- air_freight_services
- road_postal_and_courier_services
- rail_postal_and_courier_services
- sea_postal_and_courier_services
- air_postal_and_courier_services
- listed_shares_investment
- non_listed_shares_investment
- money_market_instruments_investment
- listed_bonds_investment
- non_listed_bonds_investment
- reproduce_distribute_rights_license
- patents_and_investions_rights_license
- patterns_and_designs_rights
- copyrights_rights
- franchises_and_trademarks_rights
- patents_and_inventions_disposal
- patterns_and_designs_disposal
- copyrights_disposal
- franchises_and_trademarks_disposal
- sales_of_manuscripts_sound_recordings_films
- funds_related_to_recording_productions
- software_ownership_rights_sale
- computer_services
- customised_software_sales
- non_customised_software_on_physical_media_periodic_licence_sale
- non_customised_software_on_pyisical_media_perpetual_use_sale
- non_customised_software_for_downloading_electronically_made_periodic_licence_sale
- non_customised_software_for_downloading_electronically_made_single_payment_sale
- fixed_assets_donations_to_sa_government
- fixed_assets_donations_to_corporate_entities
- property_disinvestment_by_corporate_entity_resident
- other_business_services
- institutional_investor_disinvestment
- government_services
- own_account
- donations_gifts
- family_support
- mortgage_repayment
- business_travel
- personal_travel
- management_consulting
- advertising_market_research
- cultural_recreational
- salary_resident_abroad
- salary_non_resident_in_sa
- salary_foreign_contract_in_sa
- commission_brokerage
- investment_income
- architectural_engineering
FieldValidation:
type: object
properties:
presence:
type: boolean
description: Describes whether the field is mandatory or not
readOnly: true
example: true
inclusion:
$ref: '#/components/schemas/FieldSelectValidation'
format:
type: object
description: Contains the regex to use to validate the input field
readOnly: true
example:
with: (?-mix:\A\d+\z)
PayoutMethodDetailsGHSBank:
required:
- bank_account
- bank_code
- first_name
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
bank_code:
type: string
bank_account:
type: string
birth_date:
type: string
description: Date of birth of recipient
format: date
transfer_reason:
$ref: '#/components/schemas/PayoutMethodTransferReasonEnum'
description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_code\": \"030100\",\n \"bank_account\": \"123456789\",\n \"transfer_reason\": \"third_party_person_account\"\n}\n```\n\nThe current banks supported and their bank_codes values are:\n\n- Access Bank: 280100\n- Barclays Bank: 030100\n- GCB Bank: 040100\n- Ecobank: 130100\n- First National Bank: 330100\n- Heritage Bank: 370100\n- Prudential Bank: 180100\n- Stanbic Bank: 190100\n- Standard Chartered Bank: 020100\n- United Bank for Africa: 060100\n- Zenith Bank: 120100"
PayoutMethodDetailsXOFMobile:
required:
- first_name
- last_name
- mobile_provider
- phone_number
type: object
properties:
first_name:
type: string
last_name:
type: string
phone_number:
type: string
mobile_provider:
$ref: '#/components/schemas/PayoutMethodMobileProviderEnum'
country:
$ref: '#/components/schemas/PayoutMethodCountryEnum'
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 \"phone_number\": \"+221708766123\", // E.164 international format\n \"mobile_provider\": \"orange\", // \"orange\", \"tigo\", \"emoney\" or \"free\" for Senegal; \"orange\", \"mtn\" or \"moov\" for Ivory Coast; \"orange\" or \"mobicash\" for Burkina Faso and Mali\n \"country\" // Optional; Values: \"SN\" for Senegal; \"CI\" for Ivory Coast; \"ML\" for Mali; \"BF\" for Burkina Faso; Default value is \"SN\"\n \"transfer_reason\": \"personal_account\" // mandatory for Mali payouts, optional otherwise\n}\n```"
PayinMethodDetailsMobile:
type: object
properties:
phone_number:
type: string
description: The phone number where the funds should be collected from
example: '+256129999999'
mobile_provider:
$ref: '#/components/schemas/PayoutMethodMobileProviderEnum'
country:
$ref: '#/components/schemas/PayoutMethodCountryEnum'
otp:
type: string
description: The OTP that the sender received in otp verified ussd popup ux flow.
description: "```JSON\n\"details\": {\n \"phone_number\": \"+256129999999\",\n}\n```"
PayoutMethodDetailsXOFBank:
required:
- first_name
- iban
- last_name
type: object
properties:
first_name:
type: string
last_name:
type: string
iban:
type: string
bank_name:
type: string
bank_country:
type: string
bank_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\": \"BJ0610100100144390000769\", # BBAN format\n \"bank_name\": \"Bank Of Africa Bénin\",\n \"bank_country\": \"BJ\", # ISO country code for Benin\n \"bank_code\": \"BJ061\",\n \"transfer_reason\": \"personal_account\",\n \"narration\": \"Birthday Gift\" // Optional\n}\n```\n\nSee [XOF Bank](https://docs.transferzero.com/docs/payout-details/#xofbank) documentation for the bank_code and transfer_reason lists"
securitySchemes:
AuthorizationKey:
type: apiKey
description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields
name: Authorization-Key
in: header
AuthorizationSecret:
type: apiKey
description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields
name: Authorization-Secret
in: header
AuthorizationNonce:
type: apiKey
description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields
name: Authorization-Nonce
in: header
AuthorizationSignature:
type: apiKey
description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields
name: Authorization-Signature
in: header
externalDocs:
description: API documentation and onboarding guide
url: https://docs.transferzero.com/