{
"openapi" : "3.0.2",
"info" : {
"title" : "TransferZero API",
"description" : "Reference documentation for the TransferZero API V1",
"version" : "1.0"
},
"externalDocs" : {
"description" : "API documentation and onboarding guide",
"url" : "https://docs.transferzero.com/"
},
"servers" : [ {
"url" : "https://api-sandbox.transferzero.com/v1"
}, {
"url" : "https://api.transferzero.com/v1"
} ],
"security" : [ {
"AuthorizationKey" : [ ],
"AuthorizationNonce" : [ ],
"AuthorizationSignature" : [ ]
}, {
"AuthorizationKey" : [ ],
"AuthorizationSecret" : [ ]
} ],
"paths" : {
"/accounts" : {
"get" : {
"tags" : [ "Accounts" ],
"summary" : "Fetches account balances for all currencies",
"description" : "Fetches account balances for all currencies, and returns an array of the current balances and associated currency codes.",
"operationId" : "get-accounts",
"responses" : {
"200" : {
"description" : "Array of account balances",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/AccountListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/accounts/{Currency}" : {
"get" : {
"tags" : [ "Accounts" ],
"summary" : "Fetches account balance for specified currrency",
"description" : "Fetches account balance for specified currrency, and returns current balance and associated currency code",
"operationId" : "get-account",
"parameters" : [ {
"name" : "Currency",
"in" : "path",
"description" : "Currency code of account balance to fetch\n\nExample: `/v1/accounts/USD`",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "Account balance for currency",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/AccountResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/accounts/debits" : {
"post" : {
"tags" : [ "Account Debits" ],
"summary" : "Creating an account debit",
"description" : "Creates a new account debit finding transaction through the internal balance\n\nTo successfully fund a transaction -\n- The currency needs to be the same as the input_currency on the transaction\n- The amount has to be the same as the input_amount on the transaction\n- The to_id is the id of the transaction\n- You need to have enough balance of the appropriate currency inside your wallet\n\nOnce the transaction is funded, we will immediately start trying to pay out the recipient(s).\n\nIt is also possible to create multiple account debits by supplying an array of debit objects\n",
"externalDocs" : {
"description" : "Funding Transaction guide including alternative ways to fund transactions.",
"url" : "https://docs.transferzero.com/docs/transaction-flow/#funding-transactions"
},
"operationId" : "post-accounts-debits",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DebitRequestWrapper"
},
"examples" : {
"single_debit" : {
"summary" : "Single Debit",
"value" : {
"debit" : {
"currency" : "NGN",
"amount" : "2000.0",
"to_id" : "5f44026b-7904-4c30-87d6-f8972d790ded",
"to_type" : "Transaction"
}
}
},
"multiple_debit" : {
"summary" : "Multiple Debit",
"value" : {
"debit" : [ {
"currency" : "NGN",
"amount" : 2.0,
"to_id" : "d9269c2a-7049-4625-b3b8-30e25ad33162",
"to_type" : "Transaction",
"metadata" : {
"id" : "b783a4f5-a959-4a1f-87fa-112fe6eae9e4"
}
}, {
"currency" : "NGN",
"amount" : 2.0,
"to_id" : "912973a9-e027-4768-8e98-5a8f44469bf4",
"to_type" : "Transaction",
"metadata" : {
"id" : "4900f50a-bfb6-469f-ad0e-8c8cf0ef5dfa"
}
} ]
}
}
}
}
},
"required" : true
},
"responses" : {
"201" : {
"description" : "Account Debit details",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DebitListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"422" : {
"description" : "Invalid account debit object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DebitListResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/account_validations" : {
"post" : {
"tags" : [ "Account Validation" ],
"summary" : "Validates the existence of a bank account or a mobile phone number",
"description" : "Validates the existence of a bank account or mobile phone number and returns the associated customer name",
"externalDocs" : {
"description" : "More information on account validation and bank account name enquiry",
"url" : "https://docs.transferzero.com/docs/additional-features/#account-name-enquiry"
},
"operationId" : "post-account-validations",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/AccountValidationRequest"
},
"examples" : {
"bank" : {
"summary" : "Bank Account Validation",
"value" : {
"bank_account" : "12345678",
"bank_code" : "050",
"country" : "NG",
"currency" : "NGN",
"method" : "bank"
}
},
"bank_with_iban" : {
"summary" : "Bank account Validation using IBAN in BBAN format",
"value" : {
"iban" : "CI1630120200000018678768",
"country" : "CI",
"currency" : "XOF",
"method" : "bank"
}
},
"mobile" : {
"summary" : "Mobile Phone Number Validation",
"value" : {
"phone_number" : "+233000000000",
"country" : "GH",
"currency" : "GHS",
"method" : "mobile"
}
}
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Success - Account details found",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/AccountValidationResponse"
}
}
}
},
"422" : {
"description" : "Error - Account details not found",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/AccountValidationResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/api_logs" : {
"get" : {
"tags" : [ "API Logs" ],
"summary" : "Fetch a list of API logs",
"description" : "Returns a list of API logs. Also includes information relating to the original request.",
"operationId" : "get-api-logs",
"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" : "created_at_from",
"in" : "query",
"description" : "Start date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "created_at_to",
"in" : "query",
"description" : "End date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "API logs returned within an array wrapped inside a JSON object",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ApiLogListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/api_logs/{API Log ID}" : {
"get" : {
"tags" : [ "API Logs" ],
"summary" : "Fetch an individual API log",
"description" : "Returns a single API log based on the API log ID.",
"operationId" : "get-api-log",
"parameters" : [ {
"name" : "API Log ID",
"in" : "path",
"description" : "ID of the API log to retrieve\n\nExample: `/v1/api_logs/00485ce9-532b-45e7-8518-7e5582242407`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Details of requested API log",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ApiLogResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/dlocal/balance" : {
"get" : {
"tags" : [ "dlocal balance" ],
"summary" : "Get dlocal balances",
"description" : "This endpoint retrieves dlocal account balances",
"operationId" : "get-balance",
"responses" : {
"200" : {
"description" : "Array of balances",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DlocalBalanceResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/info/currencies" : {
"get" : {
"tags" : [ "Currency Info" ],
"summary" : "Getting a list of possible requested currencies",
"description" : "Fetches a list of currencies available to use in other API requests. Usually the 3-character alpha ISO 4217 currency code (eg. USD) is used as the identifier.",
"operationId" : "info-currencies",
"responses" : {
"200" : {
"description" : "Returns the available currencies in the system",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/CurrencyListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/info/currencies/in" : {
"get" : {
"tags" : [ "Currency Info" ],
"summary" : "Getting a list of possible input currencies",
"description" : "Fetches a list of currencies available to use as the input currency in other API requests.\nUsually the 3-character alpha ISO 4217 currency code (eg. USD) is used as the identifier.\nUse this endpoint to determine the current exchange rate from a specific input currency to any output currency that's available.\n",
"operationId" : "info-currencies-in",
"parameters" : [ {
"name" : "sender_id",
"in" : "query",
"description" : "Allows the scoping of the results by `sender_id` (optional).\n\nExample: `/v1/info/currencies/in?sender_id=26ec8517-2f0d-48c0-b74f-0bccb9ab3a87`",
"required" : false,
"schema" : {
"type" : "string",
"description" : "ID of the sender to use.",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Returns the potential input currencies with their exchange rates",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/CurrencyExchangeListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/info/currencies/out" : {
"get" : {
"tags" : [ "Currency Info" ],
"summary" : "Getting a list of possible output currencies",
"description" : "Fetches a list of currencies available to use as the output currency and their exchange rates against the available input currencies.\nUsually the 3-character alpha ISO 4217 currency code (eg. USD) is used as the identifier.\n",
"operationId" : "info-currencies-out",
"parameters" : [ {
"name" : "sender_id",
"in" : "query",
"description" : "Allows the scoping of the results by `sender_id` (optional).\n\nExample: `/v1/info/currencies/out?sender_id=26ec8517-2f0d-48c0-b74f-0bccb9ab3a87`",
"required" : false,
"schema" : {
"type" : "string",
"description" : "ID of the sender to use.",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Returns the potential output currencies with their exchange rates",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/CurrencyExchangeListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/documents" : {
"get" : {
"tags" : [ "Documents" ],
"summary" : "Getting a list of documents",
"description" : "Fetches a list of documents.",
"operationId" : "get-documents",
"parameters" : [ {
"name" : "page",
"in" : "query",
"description" : "The page number to request (defaults to 1)",
"required" : false,
"schema" : {
"type" : "integer"
},
"example" : 1
}, {
"name" : "per",
"in" : "query",
"description" : "The number of results to load per page (defaults to 10)",
"required" : false,
"schema" : {
"type" : "integer"
},
"example" : 10
} ],
"responses" : {
"200" : {
"description" : "Array of documents requested",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DocumentListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
},
"post" : {
"tags" : [ "Documents" ],
"summary" : "Creating a document",
"description" : "Creates a new document",
"operationId" : "post-documents",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DocumentRequest"
}
}
},
"required" : true
},
"responses" : {
"201" : {
"description" : "Details of the created document",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DocumentResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"422" : {
"description" : "Invalid document object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DocumentResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/documents/{Document ID}" : {
"get" : {
"tags" : [ "Documents" ],
"summary" : "Fetching a document",
"description" : "Returns a single document by the Documents ID",
"operationId" : "get-document",
"parameters" : [ {
"name" : "Document ID",
"in" : "path",
"description" : "ID of the document to get.\n\nExample: `/v1/documents/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Details of requested document",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DocumentResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/info/payment_methods/in" : {
"get" : {
"tags" : [ "Payment Methods" ],
"summary" : "This method returns possible payin methods.",
"description" : "Fetching possible payin methods.\n",
"operationId" : "payment-methods-in",
"responses" : {
"200" : {
"description" : "List of possible methods",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PaymentMethodListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/info/payment_methods/out" : {
"get" : {
"tags" : [ "Payment Methods" ],
"summary" : "This method returns possible payout methods.",
"description" : "Fetching possible payout methods.\n",
"operationId" : "payment-methods-out",
"responses" : {
"200" : {
"description" : "List of possible methods",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PaymentMethodListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/logs/webhooks" : {
"get" : {
"tags" : [ "Logs" ],
"summary" : "Fetch a list of webhook logs",
"description" : "Returns a list of webhook logs. Response includes pagination.",
"operationId" : "get-webhook-logs",
"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" : "created_at_from",
"in" : "query",
"description" : "Start date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "created_at_to",
"in" : "query",
"description" : "End date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "Webhook logs returned within an array wrapped inside a JSON object",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookLogListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/logs/{Webhook Log ID}" : {
"get" : {
"tags" : [ "Logs" ],
"summary" : "Fetch an individual webhook log",
"description" : "Returns a single webhook log based on the webhook log ID.",
"operationId" : "get-webhook-log",
"parameters" : [ {
"name" : "Webhook Log ID",
"in" : "path",
"description" : "ID of the webhook log to retrieve\n\nExample: `/v1/logs/9d1ad631-f34a-4cff-9a7e-2c83e3a556df`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Details of requested webhook log",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookLogResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/payin_methods/{PayinMethod ID}" : {
"get" : {
"tags" : [ "Payin Methods" ],
"summary" : "Fetching a payin method",
"description" : "Show a payin method by id",
"operationId" : "get-payin-method",
"parameters" : [ {
"name" : "PayinMethod ID",
"in" : "path",
"description" : "ID of the payin method to get.\n\nExample: `/v1/payin_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Success",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayinMethodResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
},
"delete" : {
"tags" : [ "Payin Methods" ],
"summary" : "Deleting a payin method",
"description" : "Initiates a cancellation request for the specified payin method",
"operationId" : "delete-payin-method",
"parameters" : [ {
"name" : "PayinMethod ID",
"in" : "path",
"description" : "ID of the payin method to delete.\n\nExample: `/v1/payin_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Details of deleted payin method",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayinMethodResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Invalid payin method object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayinMethodResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
},
"patch" : {
"tags" : [ "Payin Methods" ],
"summary" : "Updating a payin method",
"description" : "Updates a single payin method by the Payin Method ID",
"operationId" : "patch-payin-method",
"parameters" : [ {
"name" : "PayinMethod ID",
"in" : "path",
"description" : "ID of the payin method to get.\n\nExample: `/v1/payin_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayinMethod"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Details of updated payin method",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayinMethodResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Invalid payin method object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayinMethodResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/payin_methods/{PayinMethod ID}/retry" : {
"post" : {
"tags" : [ "Payin Methods" ],
"summary" : "Retries PayinMethod",
"description" : "Retries the collection process for the payin method.\n\nPlease note only payin methods in `error` state can be retried.",
"operationId" : "retry-payin-method",
"parameters" : [ {
"name" : "PayinMethod ID",
"in" : "path",
"description" : "ID of the payin method whose collection process should be retried\n\nExample: `/v1/payin_methods/9d4d7b73-a94c-4979-ab57-09074fd55d33/retry`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Success",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayinMethodResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "This operation is unavailable"
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/payout_methods" : {
"get" : {
"tags" : [ "Payout Methods" ],
"summary" : "Listing payout methods",
"description" : "List available payout methods",
"operationId" : "get-payout-methods",
"parameters" : [ {
"name" : "state",
"in" : "query",
"description" : "Allows filtering results by `state` of the payout method.\n\nExample: `/v1/payout_methods?state[]=enabled`",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "enabled", "disabled" ]
}
}
}, {
"name" : "type",
"in" : "query",
"description" : "Allows filtering results by the specified type.\n\nExample: `/v1/payout_methods?type[]=NGN::Bank`",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}, {
"name" : "sender_id",
"in" : "query",
"description" : "Allows filtering results by the specified sender id.\n\nExample: `/v1/payout_methods?sender_id=bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"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" : "created_at_from",
"in" : "query",
"description" : "Start date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "created_at_to",
"in" : "query",
"description" : "End date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "Success",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
},
"post" : {
"tags" : [ "Payout Methods" ],
"summary" : "Creating a payout method",
"description" : "Creates a new payout method in our system.\n",
"operationId" : "post-payout-methods",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodRequest"
}
}
},
"required" : true
},
"responses" : {
"201" : {
"description" : "Payout Method details",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"422" : {
"description" : "Invalid payout method object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/payout_methods/{Payout Method ID}" : {
"get" : {
"tags" : [ "Payout Methods" ],
"summary" : "Fetching a payout method",
"description" : "Show a payout method by id",
"operationId" : "get-payout-method",
"parameters" : [ {
"name" : "Payout Method ID",
"in" : "path",
"description" : "ID of the payout method to get.\n\nExample: `/v1/payout_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Success",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
},
"delete" : {
"tags" : [ "Payout Methods" ],
"summary" : "Deleting a payout method",
"description" : "Deletes a single payout method by the Payout Method ID",
"operationId" : "delete-payout-method",
"parameters" : [ {
"name" : "Payout Method ID",
"in" : "path",
"description" : "ID of the payout method to delete.\n\nExample: `/v1/payout_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Details of deleted payout method",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Invalid payout method object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
},
"patch" : {
"tags" : [ "Payout Methods" ],
"summary" : "Updating a payout method",
"description" : "Updates a single payout method by the Payout Method ID",
"operationId" : "patch-payout-method",
"parameters" : [ {
"name" : "Payout Method ID",
"in" : "path",
"description" : "ID of the payout method to get.\n\nExample: `/v1/payout_methods/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethod"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Details of updated payout method",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Invalid payout method object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/recipients" : {
"get" : {
"tags" : [ "Recipients" ],
"summary" : "Getting a list of recipients with filtering",
"description" : "Fetches details of all recipients.",
"operationId" : "get-recipients",
"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" : "created_at_from",
"in" : "query",
"description" : "Start date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "created_at_to",
"in" : "query",
"description" : "End date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "amount_from",
"in" : "query",
"description" : "Minimum amount to filter recipients by amount range.\n\nAllows filtering results by the specified `amount` range. When using this filter, the `currency` should also be specified.\n\nExample: `/v1/recipients?currency=NGN&amount_from=83.76672339&amount_to=83.76672339`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "amount_to",
"in" : "query",
"description" : "Max amount to filter recipients by amount range.\n\nAllows filtering results by the specified `amount` range. When using this filter, the `currency` should also be specified.\n\nExample: `/v1/recipients?currency=NGN&amount_from=83.76672339&amount_to=83.76672339`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "state",
"in" : "query",
"description" : "Allows filtering results by `state` of recipient. See [API Documentation - Recipient state](https://docs.transferzero.com/docs/transaction-flow/#state) for possible states.\n\nExample: `/v1/recipients?state[]=error&state[]=initial`",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}, {
"name" : "currency",
"in" : "query",
"description" : "Allows filtering results by `input_currency`.\n\nAdditionally required when filtering by an amount range\nExample: `/v1/recipients?currency[]=KES¤cy[]=NGN`",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
} ],
"responses" : {
"200" : {
"description" : "Array of recipients requested",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RecipientListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
},
"/recipients/{Recipient ID}" : {
"delete" : {
"tags" : [ "Recipients" ],
"summary" : "Cancelling a recipient",
"description" : "Cancels the payment to the recipient specified in the URL path.\n\nPlease note recipients where the `may_cancel` attribute is true will be cancelled immediately. If the `may_cancel` attribute is false you can still try to cancel the recipient, however it will only gets cancelled if we will receive a confirmation from our partner that the payment has failed",
"externalDocs" : {
"description" : "More details on cancelling recipients",
"url" : "https://docs.transferzero.com/docs/transaction-flow/#cancelling-recipients-and-transactions"
},
"operationId" : "delete-recipient",
"parameters" : [ {
"name" : "Recipient ID",
"in" : "path",
"description" : "ID of recipient to cancel.\n\nExample: `/v1/recipients/9d4d7b73-a94c-4979-ab57-09074fd55d33`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Details of recipient cancelled",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RecipientResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Invalid recipient object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RecipientResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
},
"patch" : {
"tags" : [ "Recipients" ],
"summary" : "Updating a recipient",
"description" : "Updates the recipient specified in the URL path.\n\nPlease note that only recipients where the `editable` field is true can be modified. Once the recipient is modified any subsequent payout tries will be sent to the updated details.",
"operationId" : "patch-recipient",
"parameters" : [ {
"name" : "Recipient ID",
"in" : "path",
"description" : "ID of recipient to update.\n\nExample: `/v1/recipients/9d4d7b73-a94c-4979-ab57-09074fd55d33`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RecipientRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Details of the updated recipient",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RecipientResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Invalid recipient object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RecipientResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/recipients/{Recipient ID}/proof_of_payments" : {
"get" : {
"tags" : [ "Recipients" ],
"summary" : "Returns list of proof of payments",
"description" : "Returns a list of uploaded proof of payment files for a transaction recipient",
"operationId" : "proof-of-payments",
"parameters" : [ {
"name" : "Recipient ID",
"in" : "path",
"description" : "ID of the recipient for whom the proof of payments will be returned.\n\nExample: `/v1/recipients/9d4d7b73-a94c-4979-ab57-09074fd55d33/proof_of_payments`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Collection of proof of payment objects",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ProofOfPaymentListResponse"
}
}
}
},
"422" : {
"description" : "Unable to process the request."
}
}
}
},
"/senders" : {
"get" : {
"tags" : [ "Senders" ],
"summary" : "Listing senders",
"description" : "Get a list of available senders",
"operationId" : "get-senders",
"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" : "created_at_from",
"in" : "query",
"description" : "Start date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "created_at_to",
"in" : "query",
"description" : "End date to filter recipients by created_at range\nAllows filtering results by the specified `created_at` timeframe.\n\nExample: `/v1/recipients?created_at_from=2018-06-06&created_at_to=2018-06-08`",
"required" : false,
"schema" : {
"type" : "string"
}
}, {
"name" : "external_id",
"in" : "query",
"description" : "Allows filtering results by `external_id`.\n\nExample: `/v1/senders?external_id=26ec8517-2f0d-48c0-b74f-0bccb9ab3a87`",
"required" : false,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "Array of senders requested",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
},
"post" : {
"tags" : [ "Senders" ],
"summary" : "Creating a sender",
"description" : "Creates a new sender in our system.\n",
"operationId" : "post-senders",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderRequest"
},
"example" : "{\n \"sender\": {\n \"country\": \"UG\",\n \"phone_number\": \"+256752403639\",\n \"email\": \"example@home.org\",\n \"first_name\": \"Johnny\",\n \"last_name\": \"English\",\n \"city\": \"Kampala\",\n \"street\": \"Unknown 17-3\",\n \"address_description\": \"Description of address\",\n \"postal_code\": \"798983\",\n \"birth_date\": \"1900-12-31\",\n \"documents\": [\n {\n \"upload\": \"data:image/png;base64,iVBORw0KGg...lFTkSuQmCC\",\n \"upload_file_name\": \"example.png\",\n \"metadata\": {\n \"my\": \"data\"\n }\n }\n ],\n \"politically_exposed_people\": [\n {\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 \"ip\": \"127.0.0.1\",\n \"external_id\": \"806ec63a-a5a7-43cc-9d75-1ee74fbcc026\",\n \"metadata\": {\n \"my\": \"data\"\n }\n }\n}"
}
},
"required" : true
},
"responses" : {
"201" : {
"description" : "Sender details",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"422" : {
"description" : "Invalid sender object (includes errors object and duplicate sender if external_id is already in use)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/senders/{Sender ID}" : {
"get" : {
"tags" : [ "Senders" ],
"summary" : "Fetching a sender",
"description" : "Returns a single sender by the Sender ID",
"operationId" : "get-sender",
"parameters" : [ {
"name" : "Sender ID",
"in" : "path",
"description" : "ID of the sender to get.\n\nExample: `/v1/senders/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Details of requested sender",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
},
"delete" : {
"tags" : [ "Senders" ],
"summary" : "Deleting a sender",
"description" : "Deletes a single sender by the Sender ID",
"operationId" : "delete-sender",
"parameters" : [ {
"name" : "Sender ID",
"in" : "path",
"description" : "ID of the sender to delete.\n\nExample: `/v1/senders/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Details of deleted sender",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Invalid sender object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
},
"patch" : {
"tags" : [ "Senders" ],
"summary" : "Updating a sender",
"description" : "Updates a single sender by the Sender ID",
"operationId" : "patch-sender",
"parameters" : [ {
"name" : "Sender ID",
"in" : "path",
"description" : "ID of the sender to get.\n\nExample: `/v1/senders/bf9ff782-e182-45ac-abea-5bce83ad6670`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Details of updated sender",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Invalid sender object (includes errors object)",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/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`.\n\nExample: `/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`.\n\nExample: `/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`.\n\nExample: `/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.\nTransactions facilitate money movement from one Sender in a specific currency to one or multiple Recipients in another currency.\n\nThe main flow of a successful transaction flow is the following -\n- Transaction is created linking the Sender to the Recipient(s) with the requested amounts.\n- Once the sender is KYC'd and approved the transaction can be funded.\n- Once the transaction is funded, we will initiate the payout to the recipient(s).\n- 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.\n\nNote 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\nthe provided Transaction ID.",
"operationId" : "get-transaction",
"parameters" : [ {
"name" : "Transaction ID",
"in" : "path",
"description" : "ID of the transaction.\n\nExample: `/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.\nIt allows you to emulate a payin without paying actual money.\n",
"operationId" : "payin-transaction",
"parameters" : [ {
"name" : "Transaction ID",
"in" : "path",
"description" : "ID of the transaction to payin.\n\nExample: `/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.\nIt allows you to emulate the payout of a transaction after payin.\n",
"operationId" : "payout-transaction",
"parameters" : [ {
"name" : "Transaction ID",
"in" : "path",
"description" : "ID of the transaction to payout.\n\nExample: `/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."
}
}
}
},
"/webhooks" : {
"get" : {
"tags" : [ "Webhooks" ],
"summary" : "Listing webhooks",
"description" : "Get a list of created webhooks",
"operationId" : "get-webhooks",
"parameters" : [ {
"name" : "page",
"in" : "query",
"description" : "The page number to request (defaults to 1)",
"required" : false,
"schema" : {
"type" : "integer"
},
"example" : 1
}, {
"name" : "per",
"in" : "query",
"description" : "The number of results to load per page (defaults to 10)",
"required" : false,
"schema" : {
"type" : "integer"
},
"example" : 10
} ],
"responses" : {
"200" : {
"description" : "Array of webhooks requested. A paginated list of the webhooks created by the requesting API key",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookDefinitionListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
},
"post" : {
"tags" : [ "Webhooks" ],
"summary" : "Creating a webhook",
"description" : "Creates a new webhook, subscribing the provided endpoint to the specified event(s)\n",
"externalDocs" : {
"description" : "More information about webhooks",
"url" : "https://docs.transferzero.com/docs/architecture/#webhooks"
},
"operationId" : "post-webhooks",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookDefinitionRequest"
},
"example" : {
"webhook" : {
"url" : "http://myhost.com/for/transaction.paid_in",
"events" : [ "transaction.paid_in" ],
"metadata" : {
"my" : "data"
}
}
}
}
},
"required" : true
},
"responses" : {
"201" : {
"description" : "Details of created webhook",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookDefinitionResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"422" : {
"description" : "Webhook details and errors",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookDefinitionResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
},
"callbacks" : {
"recipient" : {
"{$request.body#/webhook/url}" : {
"post" : {
"description" : "Callback object returning details on the triggered recipient event for example when a payment is unsuccessful and there's an error",
"externalDocs" : {
"description" : "More information about webhooks",
"url" : "https://docs.transferzero.com/docs/architecture/#webhooks"
},
"operationId" : "trigger-recipient-webhook",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RecipientWebhook"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times"
}
},
"x-callback-request" : true
}
}
},
"transaction" : {
"{$request.body#/webhook/url}" : {
"post" : {
"description" : "Callback object returning details on the triggered transaction event, for example when a transaction gets paid out",
"externalDocs" : {
"description" : "More information about webhooks",
"url" : "https://docs.transferzero.com/docs/architecture/#webhooks"
},
"operationId" : "trigger-transaction-webhook",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/TransactionWebhook"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times"
}
},
"x-callback-request" : true
}
}
},
"sender" : {
"{$request.body#/webhook/url}" : {
"post" : {
"description" : "Callback object returning details on the triggered sender event, for example when a sender gets approved",
"externalDocs" : {
"description" : "More information about webhooks",
"url" : "https://docs.transferzero.com/docs/architecture/#webhooks"
},
"operationId" : "trigger-sender-webhook",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SenderWebhook"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times"
}
},
"x-callback-request" : true
}
}
},
"document" : {
"{$request.body#/webhook/url}" : {
"post" : {
"description" : "Callback object returning details on the triggered document event",
"externalDocs" : {
"description" : "More information about webhooks",
"url" : "https://docs.transferzero.com/docs/architecture/#webhooks"
},
"operationId" : "trigger-document-webhook",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DocumentWebhook"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times"
}
},
"x-callback-request" : true
}
}
},
"payout_method" : {
"{$request.body#/webhook/url}" : {
"post" : {
"description" : "Callback object returning details on the triggered payout method event",
"externalDocs" : {
"description" : "More information about webhooks",
"url" : "https://docs.transferzero.com/docs/architecture/#webhooks"
},
"operationId" : "trigger-payout-method-webhook",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/PayoutMethodWebhook"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Your server returns this code if it accepts the callback. Any other code will be considered as a failure, and the callback will be re-sent a short while later until there is either a 200 response or we have retried the callback 5 times"
}
},
"x-callback-request" : true
}
}
}
}
}
},
"/webhooks/{Webhook ID}" : {
"get" : {
"tags" : [ "Webhooks" ],
"summary" : "Find a webhook's details",
"description" : "Look up a webhook's details with its ID",
"operationId" : "get-webhook",
"parameters" : [ {
"name" : "Webhook ID",
"in" : "path",
"description" : "The ID of the Webhook to look up\n\nExample: `/v1/webhooks/9d4d7b73-a94c-4979-ab57-09074fd55d33`",
"required" : true,
"schema" : {
"type" : "string",
"format" : "uuid"
}
} ],
"responses" : {
"200" : {
"description" : "Webhook details",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookDefinitionResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
},
"delete" : {
"tags" : [ "Webhooks" ],
"summary" : "Unsubscribing from a webhook",
"description" : "Unsubscribes from a webhook specified",
"operationId" : "delete-webhook",
"parameters" : [ {
"name" : "Webhook ID",
"in" : "path",
"description" : "The ID of webhook to cancel.\n\nExample: `/v1/webhooks/9d4d7b73-a94c-4979-ab57-09074fd55d33`",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "Success",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookDefinitionResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"404" : {
"description" : "Resource Not Found."
},
"422" : {
"description" : "Webhook details and errors",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookDefinitionResponse"
}
}
}
},
"500" : {
"description" : "Internal Server Error."
}
}
}
},
"/webhooks/events" : {
"get" : {
"tags" : [ "Webhooks" ],
"summary" : "Find possible webhook events",
"description" : "Fetching possible webhook events",
"operationId" : "get-webhook-events",
"responses" : {
"200" : {
"description" : "Webhook events",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebhookDefinitionEventListResponse"
}
}
}
},
"401" : {
"description" : "Authentication information is missing or invalid."
},
"500" : {
"description" : "Internal Server Error."
}
},
"x-group-parameters" : true
}
}
},
"components" : {
"schemas" : {
"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"
}
},
"AccountListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/Account"
}
},
"meta" : {
"$ref" : "#/components/schemas/AccountMeta"
}
},
"readOnly" : true,
"example" : {
"meta" : {
"negative_balance" : false
},
"object" : [ {
"amount" : 1000.0,
"amount_after_pending" : 1000.0,
"currency" : "USD"
}, {
"amount" : 1000.0,
"amount_after_pending" : 1000.0,
"currency" : "USD"
} ]
}
},
"AccountResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/Account"
},
"meta" : {
"$ref" : "#/components/schemas/AccountMeta"
}
},
"readOnly" : true,
"example" : {
"meta" : {
"negative_balance" : false
},
"object" : {
"amount" : 1000.0,
"amount_after_pending" : 1000.0,
"currency" : "USD"
}
}
},
"DebitRequestWrapper" : {
"example" : {
"debit" : {
"currency" : "NGN",
"amount" : "2000.0",
"to_id" : "5f44026b-7904-4c30-87d6-f8972d790ded",
"to_type" : "Transaction"
}
},
"oneOf" : [ {
"$ref" : "#/components/schemas/DebitRequest"
}, {
"$ref" : "#/components/schemas/DebitListRequest"
} ]
},
"DebitListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/Debit"
}
},
"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" : [ {
"to_type" : "Transaction",
"amount" : 10000,
"metadata" : { },
"to_id" : "5f44026b-7904-4c30-87d6-f8972d790ded",
"created_at" : "2000-01-23T04:56:07.000+00:00",
"currency" : "NGN",
"id" : "5f44026b-7904-4c30-87d6-f8972d790ded",
"running_balance" : 2000000,
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
},
"usd_amount" : 200.06211683187206
}, {
"to_type" : "Transaction",
"amount" : 10000,
"metadata" : { },
"to_id" : "5f44026b-7904-4c30-87d6-f8972d790ded",
"created_at" : "2000-01-23T04:56:07.000+00:00",
"currency" : "NGN",
"id" : "5f44026b-7904-4c30-87d6-f8972d790ded",
"running_balance" : 2000000,
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
},
"usd_amount" : 200.06211683187206
} ]
}
},
"AccountValidationRequest" : {
"required" : [ "country", "currency", "method" ],
"type" : "object",
"properties" : {
"bank_account" : {
"type" : "string",
"description" : "Account Number to query",
"writeOnly" : true
},
"bank_code" : {
"type" : "string",
"description" : "Bank Code to query - same codes are used as for creating the transactions",
"writeOnly" : true
},
"iban" : {
"type" : "string",
"description" : "IBAN to query - BBAN format for XOF bank accounts",
"writeOnly" : true
},
"phone_number" : {
"type" : "string",
"description" : "Phone number to query in E.164 format",
"writeOnly" : true,
"example" : "+233000000000"
},
"mobile_provider" : {
"$ref" : "#/components/schemas/PayoutMethodMobileProviderEnum"
},
"country" : {
"type" : "string",
"description" : "Country of account in 2-character alpha ISO 3166-2 country format",
"writeOnly" : true,
"enum" : [ "BF", "BJ", "CG", "CI", "CM", "GA", "GH", "KE", "NG", "SN", "TD", "TG", "UG" ]
},
"currency" : {
"type" : "string",
"description" : "The currency the bank account is in",
"writeOnly" : true,
"enum" : [ "NGN", "GHS", "KES", "XOF", "UGX", "XAF" ]
},
"method" : {
"type" : "string",
"description" : "The method of the payment. Currently bank and mobile are supported",
"writeOnly" : true,
"enum" : [ "bank", "mobile" ]
}
},
"example" : {
"bank_code" : "bank_code",
"country" : "BF",
"mobile_provider" : "orange",
"method" : "bank",
"iban" : "iban",
"phone_number" : "+233000000000",
"currency" : "NGN",
"bank_account" : "bank_account"
}
},
"AccountValidationResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/AccountValidationResult"
},
"meta" : {
"$ref" : "#/components/schemas/AccountValidationError"
}
},
"readOnly" : true,
"example" : {
"object" : {
"account_name" : "John Smith",
"mapped_mobile_provider" : "mtn"
}
}
},
"ApiLogListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"description" : "Array of API log objects",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/ApiLog"
}
},
"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" : [ {
"response_headers" : {
"X-Frame-Options" : "SAMEORIGIN",
"X-XSS-Protection" : "1; mode=block",
"X-Content-Type-Options" : "nosniff",
"Content-Type" : "application/json; charset=UTF-8"
},
"request_body" : "{\"message\":\"Email dispatched: Accepted (user@transferzero.com)\"}",
"response_status" : "200",
"request_headers" : {
"HTTP_VERSION" : "HTTP/1.1",
"HTTP_ACCEPT" : "application/json",
"HTTP_USER_AGENT" : "TransferZero Ruby",
"HTTP_AUTHORIZATION_NONCE" : "0000",
"HTTP_AUTHORIZATION_KEY" : "0000",
"HTTP_AUTHORIZATION_SIGNATURE" : "0000",
"HTTP_CONNECTION" : "close",
"HTTP_HOST" : "localhost:3002"
},
"response_body" : "{\"object\":{\"result\":0}}",
"created_at" : "2019-01-11T00:00:00.001+0000",
"id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"request_method" : "POST",
"request_url" : "https://api.transferzero/v1/transactions/validate"
}, {
"response_headers" : {
"X-Frame-Options" : "SAMEORIGIN",
"X-XSS-Protection" : "1; mode=block",
"X-Content-Type-Options" : "nosniff",
"Content-Type" : "application/json; charset=UTF-8"
},
"request_body" : "{\"message\":\"Email dispatched: Accepted (user@transferzero.com)\"}",
"response_status" : "200",
"request_headers" : {
"HTTP_VERSION" : "HTTP/1.1",
"HTTP_ACCEPT" : "application/json",
"HTTP_USER_AGENT" : "TransferZero Ruby",
"HTTP_AUTHORIZATION_NONCE" : "0000",
"HTTP_AUTHORIZATION_KEY" : "0000",
"HTTP_AUTHORIZATION_SIGNATURE" : "0000",
"HTTP_CONNECTION" : "close",
"HTTP_HOST" : "localhost:3002"
},
"response_body" : "{\"object\":{\"result\":0}}",
"created_at" : "2019-01-11T00:00:00.001+0000",
"id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"request_method" : "POST",
"request_url" : "https://api.transferzero/v1/transactions/validate"
} ]
}
},
"ApiLogResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/ApiLog"
}
},
"readOnly" : true,
"example" : {
"object" : {
"response_headers" : {
"X-Frame-Options" : "SAMEORIGIN",
"X-XSS-Protection" : "1; mode=block",
"X-Content-Type-Options" : "nosniff",
"Content-Type" : "application/json; charset=UTF-8"
},
"request_body" : "{\"message\":\"Email dispatched: Accepted (user@transferzero.com)\"}",
"response_status" : "200",
"request_headers" : {
"HTTP_VERSION" : "HTTP/1.1",
"HTTP_ACCEPT" : "application/json",
"HTTP_USER_AGENT" : "TransferZero Ruby",
"HTTP_AUTHORIZATION_NONCE" : "0000",
"HTTP_AUTHORIZATION_KEY" : "0000",
"HTTP_AUTHORIZATION_SIGNATURE" : "0000",
"HTTP_CONNECTION" : "close",
"HTTP_HOST" : "localhost:3002"
},
"response_body" : "{\"object\":{\"result\":0}}",
"created_at" : "2019-01-11T00:00:00.001+0000",
"id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"request_method" : "POST",
"request_url" : "https://api.transferzero/v1/transactions/validate"
}
}
},
"DlocalBalanceResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/DlocalBalance"
}
}
},
"readOnly" : true,
"example" : {
"object" : [ {
"current_balance_date" : "2026-02-24",
"currency" : "USD",
"available_balance" : 1000,
"previous_day_closing_balance" : 1000
}, {
"current_balance_date" : "2026-02-24",
"currency" : "USD",
"available_balance" : 1000,
"previous_day_closing_balance" : 1000
} ]
}
},
"CurrencyListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/Currency"
}
}
},
"description" : "List of possible currencies",
"readOnly" : true,
"example" : {
"object" : [ {
"code" : "USD",
"name" : "United States Dollar",
"symbol" : "$",
"decimals" : 2,
"subunit_to_unit" : 100,
"primary" : false,
"min" : "0.000000000000000000000001",
"max" : "999999999999999999999999999.0"
}, {
"code" : "KES",
"name" : "Kenyan Shilling",
"symbol" : "KSh",
"decimals" : 2,
"subunit_to_unit" : 100,
"primary" : true,
"min" : "0.000000000000000000000001",
"max" : "999999999999999999999999999.0"
} ]
}
},
"CurrencyExchangeListResponse" : {
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/CurrencyExchange"
}
}
},
"description" : "List of possible currency exchange pairs",
"readOnly" : true,
"example" : {
"object" : [ {
"code" : "NGN",
"name" : "Nigerian Naira",
"symbol" : "₦",
"decimals" : 2,
"subunit_to_unit" : 100,
"primary" : true,
"min" : "1000.0",
"max" : "10000000.0",
"margin" : "3.0",
"usd_equivalent" : "0.002743485349395299586854627",
"opposites" : [ {
"code" : "CNY",
"name" : "Chinese Renminbi Yuan",
"symbol" : "¥",
"decimals" : 2,
"subunit_to_unit" : 100,
"primary" : true,
"min" : "100.0",
"max" : "50000.0",
"margin" : "3.0",
"usd_equivalent" : "0.14596446284532970096399939",
"rate" : 0.01784400294334069,
"mtm_rate" : 56
}, {
"code" : "XOF",
"name" : "West African Cfa Franc",
"symbol" : "Fr",
"decimals" : 0,
"subunit_to_unit" : 1,
"primary" : true,
"min" : "1.0",
"max" : "100.0",
"margin" : "3.0",
"usd_equivalent" : "0.001728621452207475495474445",
"rate" : 1.5132,
"mtm_rate" : 0.660851176315094
} ]
}, {
"code" : "UGX",
"name" : "Ugandan Shilling",
"symbol" : "UGX",
"decimals" : 2,
"subunit_to_unit" : 100,
"primary" : true,
"min" : "1000.0",
"max" : "4000000.0",
"margin" : "3.0",
"usd_equivalent" : "0.000268161238738656449967193",
"opposites" : [ {
"code" : "CNY",
"name" : "Chinese Renminbi Yuan",
"symbol" : "¥",
"decimals" : 2,
"subunit_to_unit" : 100,
"primary" : true,
"min" : "100.0",
"max" : "50000.0",
"margin" : "3.0",
"usd_equivalent" : "0.14596446284532970096399939",
"rate" : 0.0017820529497794776,
"mtm_rate" : 561.1505539853607
}, {
"code" : "NGN",
"name" : "Nigerian Naira",
"symbol" : "₦",
"decimals" : 2,
"subunit_to_unit" : 100,
"primary" : true,
"min" : "1000.0",
"max" : "10000000.0",
"margin" : "3.0",
"usd_equivalent" : "0.002743485349395299586854627",
"rate" : 0.09613478691774034,
"mtm_rate" : 10.402061855670103
} ]
} ]
}
},
"DocumentListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/Document"
}
},
"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" : { },
"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"
}, {
"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"
} ]
}
},
"DocumentRequest" : {
"type" : "object",
"properties" : {
"document" : {
"$ref" : "#/components/schemas/Document"
}
},
"example" : {
"document" : {
"upload" : "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAACXBIWXMAAAsT\n3Y2wAAAAAElFTkSuQmCC(...)",
"upload_file_name" : "passport.png",
"metadata" : {
"meta" : "data"
}
}
}
},
"DocumentResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/Document"
}
},
"readOnly" : true,
"example" : {
"object" : {
"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"
}
}
},
"PaymentMethodListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/PaymentMethodOpposite"
}
}
},
"readOnly" : true,
"example" : {
"object" : [ {
"type" : "NGN::Bank",
"provider" : "interswitch",
"otc_permitted" : false,
"details" : [ "url" ],
"opposites" : [ {
"type" : "CNY::Bank",
"provider" : "melotic",
"otc_permitted" : false,
"details" : [ "email", "name", "phone_number", "bank_account" ],
"default" : true,
"fields" : {
"email" : {
"type" : "input",
"validations" : {
"format" : "\\A((\\w+([\\-+.]\\w+)*@[a-zA-Z0-9]+([\\-\\.][a-zA-Z0-9]+)*)*){3,320}\\z"
}
},
"name" : {
"type" : "input",
"validations" : {
"presence" : true
}
},
"phone_number" : {
"type" : "input",
"validations" : {
"presence" : true,
"invalid" : true
}
},
"bank_account" : {
"type" : "input",
"validations" : {
"presence" : true,
"invalid" : true
}
}
}
}, {
"type" : "USD::Manual::Bank",
"provider" : "bank_transfer",
"otc_permitted" : false,
"details" : [ "email", "first_name", "last_name", "bank_name", "bank_account", "routing_number" ],
"default" : true,
"fields" : {
"email" : {
"type" : "input",
"validations" : {
"format" : "\\A((\\w+([\\-+.]\\w+)*@[a-zA-Z0-9]+([\\-\\.][a-zA-Z0-9]+)*)*){3,320}\\z"
}
},
"first_name" : {
"type" : "input"
},
"last_name" : {
"type" : "input"
},
"bank_name" : {
"type" : "input"
},
"bank_account" : {
"type" : "input"
},
"routing_number" : {
"type" : "input"
}
}
} ]
} ]
}
},
"PaymentMethodOpposite" : {
"allOf" : [ {
"$ref" : "#/components/schemas/PaymentMethod"
}, {
"properties" : {
"opposites" : {
"type" : "array",
"description" : "List of all providers that can be used in conjunction with the main provider",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/PaymentMethod"
}
}
}
} ]
},
"PaymentMethod" : {
"type" : "object",
"properties" : {
"type" : {
"type" : "string",
"description" : "Details currency and type of payment.",
"readOnly" : true,
"example" : "NGN::Bank"
},
"provider" : {
"type" : "string",
"description" : "Identifies the payment provider.",
"readOnly" : true,
"example" : "Interswitch"
},
"otc_permitted" : {
"type" : "boolean",
"description" : "Are over the counter transactions permitted?",
"readOnly" : true,
"example" : false
},
"details" : {
"type" : "array",
"description" : "Fields required to make the payment depending on type.",
"readOnly" : true,
"example" : [ "email", "first_name", "last_name", "address" ],
"items" : {
"type" : "string"
}
},
"default" : {
"type" : "boolean",
"description" : "Boolean revealing whether this is the default payout method. Only present on payout methods",
"readOnly" : true,
"example" : false
},
"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" : "Describes an available payment provider",
"readOnly" : true,
"example" : {
"type" : "GHS::Bank",
"provider" : "etranzact",
"otc_permitted" : false,
"details" : [ "email", "first_name", "last_name", "bank_code", "bank_account", "bank_account_title" ],
"default" : true,
"fields" : {
"email" : {
"type" : "input",
"validations" : {
"format" : "\\A((\\w+([\\-+.]\\w+)*@[a-zA-Z0-9]+([\\-\\.][a-zA-Z0-9]+)*)*){3,320}\\z"
}
},
"first_name" : {
"type" : "input",
"validations" : {
"presence" : true
}
},
"last_name" : {
"type" : "input",
"validations" : {
"presence" : true
}
},
"bank_code" : {
"type" : "select",
"options" : {
"025" : "ACCESS BANK",
"008" : "ADB"
},
"validations" : {
"presence" : true,
"inclusion" : {
"in" : {
"025" : "ACCESS BANK",
"008" : "ADB"
}
}
}
},
"bank_account" : {
"type" : "input",
"validations" : {
"presence" : true
}
},
"bank_account_title" : {
"type" : "input",
"validations" : {
"presence" : true
}
}
}
}
},
"WebhookLogListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"description" : "Array of webhook log objects",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/WebhookLog"
}
},
"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" : {
"tries" : 15,
"request" : {
"headers" : {
"Content-Type" : "application/json",
"Authorization-Nonce" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Key" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Signature" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Accept-Encoding" : "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
"Accept" : "*/*",
"User-Agent" : "Ruby",
"Host" : "localhost:3000",
"Content-Length" : "3549"
},
"body" : "{\"webhook\":\"54cbd6f2-b920-41e9-a225-b1000e024787\",\"event\":\"transaction.mispaid\",\"object\":{\"id\":\"cbcea909-85e3-448f-bd07-b9ecdff6e971\"}}",
"url" : "http://localhost:3000"
},
"instance_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"response" : {
"headers" : {
"date" : "Fri, 11 Jan 2019 09:00:00 GMT",
"connection" : "close",
"content-type" : "text/html; charset=utf-8",
"x-web-console-session-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-web-console-mount-point" : "/__web_console",
"x-request-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-runtime" : "0.484015",
"content-length" : "145453"
},
"body" : " Action Controller: Exception caught",
"status" : "500"
},
"attempt_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"params" : {
"metadata" : { },
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "http://webhook.site/webhooks",
"events" : [ "transaction.paid_in", "transaction.paid_in" ],
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
}
},
"event" : "transaction.mispaid",
"instance_type" : "Transaction",
"app_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"api_key_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"parent_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"created_at" : "2018-12-31T23:59:50.059+0000",
"id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"message" : "Transaction(a0696374-de2f-4b4e-a2d7-cb4e0a1240c0) transaction.mispaid pending!",
"parent_type" : "Webhook"
}, {
"metadata" : {
"tries" : 15,
"request" : {
"headers" : {
"Content-Type" : "application/json",
"Authorization-Nonce" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Key" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Signature" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Accept-Encoding" : "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
"Accept" : "*/*",
"User-Agent" : "Ruby",
"Host" : "localhost:3000",
"Content-Length" : "3549"
},
"body" : "{\"webhook\":\"54cbd6f2-b920-41e9-a225-b1000e024787\",\"event\":\"transaction.mispaid\",\"object\":{\"id\":\"cbcea909-85e3-448f-bd07-b9ecdff6e971\"}}",
"url" : "http://localhost:3000"
},
"instance_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"response" : {
"headers" : {
"date" : "Fri, 11 Jan 2019 09:00:00 GMT",
"connection" : "close",
"content-type" : "text/html; charset=utf-8",
"x-web-console-session-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-web-console-mount-point" : "/__web_console",
"x-request-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-runtime" : "0.484015",
"content-length" : "145453"
},
"body" : " Action Controller: Exception caught",
"status" : "500"
},
"attempt_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"params" : {
"metadata" : { },
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "http://webhook.site/webhooks",
"events" : [ "transaction.paid_in", "transaction.paid_in" ],
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
}
},
"event" : "transaction.mispaid",
"instance_type" : "Transaction",
"app_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"api_key_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"parent_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"created_at" : "2018-12-31T23:59:50.059+0000",
"id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"message" : "Transaction(a0696374-de2f-4b4e-a2d7-cb4e0a1240c0) transaction.mispaid pending!",
"parent_type" : "Webhook"
} ]
}
},
"WebhookLogResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/WebhookLog"
}
},
"readOnly" : true,
"example" : {
"object" : {
"metadata" : {
"tries" : 15,
"request" : {
"headers" : {
"Content-Type" : "application/json",
"Authorization-Nonce" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Key" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Signature" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Accept-Encoding" : "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
"Accept" : "*/*",
"User-Agent" : "Ruby",
"Host" : "localhost:3000",
"Content-Length" : "3549"
},
"body" : "{\"webhook\":\"54cbd6f2-b920-41e9-a225-b1000e024787\",\"event\":\"transaction.mispaid\",\"object\":{\"id\":\"cbcea909-85e3-448f-bd07-b9ecdff6e971\"}}",
"url" : "http://localhost:3000"
},
"instance_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"response" : {
"headers" : {
"date" : "Fri, 11 Jan 2019 09:00:00 GMT",
"connection" : "close",
"content-type" : "text/html; charset=utf-8",
"x-web-console-session-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-web-console-mount-point" : "/__web_console",
"x-request-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-runtime" : "0.484015",
"content-length" : "145453"
},
"body" : " Action Controller: Exception caught",
"status" : "500"
},
"attempt_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"params" : {
"metadata" : { },
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "http://webhook.site/webhooks",
"events" : [ "transaction.paid_in", "transaction.paid_in" ],
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
}
},
"event" : "transaction.mispaid",
"instance_type" : "Transaction",
"app_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"api_key_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"parent_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"created_at" : "2018-12-31T23:59:50.059+0000",
"id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"message" : "Transaction(a0696374-de2f-4b4e-a2d7-cb4e0a1240c0) transaction.mispaid pending!",
"parent_type" : "Webhook"
}
}
},
"PayinMethodResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/PayinMethod"
}
},
"readOnly" : true,
"example" : {
"object" : {
"type" : "GHS::Mobile",
"ux_flow" : "ussd_popup",
"in_details" : {
"phone_number" : "+233541299999",
"mobile_provider" : "vodafone"
}
}
}
},
"PayinMethod" : {
"type" : "object",
"properties" : {
"type" : {
"type" : "string",
"description" : "Describes how the payment should be requested from the sender.\n\nPossible values:\n- `GHS::Mobile`: GHS mobile collections\n- `UGX::Mobile`: UGX mobile collections\n- `XOF::Mobile`: XOF mobile collections\n- `NGN::Bank`: NGN bank collections\n- `EUR::Bank`: EUR IBAN collections\n- `GBP::Bank`: GBP IBAN collections\n",
"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"
}
},
"PayinMethodUxFlow" : {
"type" : "string",
"description" : "Describes the collection experience that will be presented to\nthe sender. Can be one of the following:\n\n* `ussd_popup`: Payment prompt is pushed to the sender's phone. They can approve or decline. Supported for GHS::Mobile, UGX::Mobile\n* `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)\n* `ussd_menu_approval`: Sender has to dial a USSD code and navigate to a list of payments to approve.\n* `otp_verified_ussd_popup`: Sender receives and validates an OTP then a payment prompt is pushed if the OTP they submit is valid.\n* `bank_transfer`: For bank collections. Sender should send funds to the bank account details specified in out_details. Supported for EUR::Bank, GBP::Bank\n* `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" ]
},
"PayinMethodDetails" : {
"description" : "Fields needed by the payment processor. Depends on the chose payin type.\n\nSee the appropriate model details for more info:\n\n- `NGN::Bank`: see [`PayinMethodDetailsNGNBank`](#model-PayinMethodDetailsNGNBank)\n- `GHS::Mobile`: see [`PayinMethodDetailsMobile`](#model-PayinMethodDetailsMobile)\n- `UGX::Mobile`: see [`PayinMethodDetailsMobile`](#model-PayinMethodDetailsMobile)\n\nNote that some payin processors don't require additional input, these include `lhv` through `EUR::Bank` and `GBP::Bank`.\nSome providers like `providus` also have all of their fields set as optional, so you might not want to set any values.\nTo use these providers please set this value to `{}` (an empty hash)\n",
"oneOf" : [ {
"$ref" : "#/components/schemas/PayinMethodDetailsNGNBank"
}, {
"$ref" : "#/components/schemas/PayinMethodDetailsMobile"
}, {
"$ref" : "#/components/schemas/PayinMethodDetailsBTC"
} ]
},
"PayinMethodState" : {
"type" : "string",
"description" : "The state of the payin method, which can be one of the following:\n\n* `incomplete`: Some fields need to be filled in in_details before we can initiate the collection request.\n* `initial`: All required fields in in_details are present and collection process with the sender will start.\n* `pending`: Collection process has been started, waiting for sender to send funds.\n* `success`: Collection succeeded and funds have been cleared.\n* `processing`: Collection succeeded but waiting for funds to fully clear.\n* `error`: Collection failed. No funds received from sender. You can update or retry the PayinMethod.\n* `mispaid`: Collection succeeded but sender sent the wrong amount.\n* `canceled`: The transaction has been canceled and we will refund the sender soon.\n* `refunded`: The sender has been refunded the amount they sent in.\n* `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" ]
},
"PayoutMethodListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/PayoutMethod"
}
},
"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" : { },
"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"
} ]
}
}, {
"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"
} ]
}
} ]
}
},
"PayoutMethodRequest" : {
"type" : "object",
"properties" : {
"payout_method" : {
"$ref" : "#/components/schemas/PayoutMethod"
}
},
"example" : {
"payout_method" : {
"type" : "NGN::Bank",
"details" : {
"bank_code" : "058",
"bank_account" : "123456789",
"bank_account_type" : "10",
"last_name" : "English",
"first_name" : "Johnny",
"street" : "1 Main Street"
},
"metadata" : {
"my" : "data"
}
}
}
},
"PayoutMethodResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/PayoutMethod"
}
},
"readOnly" : true,
"example" : {
"object" : {
"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"
} ]
}
}
}
},
"PayoutMethod" : {
"type" : "object",
"properties" : {
"type" : {
"type" : "string",
"description" : "Contains the currency to send the money to, and the type of the money movement\n\nCommonly used payout types are:\n\n- `NGN::Bank` - for Nigerian bank account payments.\n- `GHS::Bank` - for Ghanaian bank account payments.\n- `GHS::Mobile` - for Ghanaian mobile money payments.\n- `UGX::Mobile` - for Ugandan mobile money payments.\n- `XOF::Mobile` - for mobile money payments to West-Africa.\n- `XOF::Bank` - for Senegalese bank account payments.\n- `XOF::Cash` - for Senegalese cash remittance payments.\n- `MAD::Cash` - for Moroccan cash remittance payments.\n- `EUR::Bank` - for IBAN bank transfers in EUR.\n- `GBP::Bank` - for IBAN bank and FP accounts transfers in GBP.\n- `ZAR::Bank` - for South Africa bank account payments.\n- `USD::Bank` - for USD account payments. *** Currently for Egypt, Nigeria and United States only and in Beta phase ***\n- `USD::Cash` - for USD cash remittance payments. *** Currently for Nigeria only and in Beta phase ***\n- `KES::Bank` - for Kenyan bank account payments.\n- `KES::Mobile` - for Kenyan mobile money payments.\n- `XAF::Mobile` - for mobile money payments to Central African (CEMAC) countries. *** Currently in Beta phase ***\n- `XAF::Bank` - for Cameroon bank account payments.\n- `GNF::Mobile` - for mobile money payments to Guinea.\n- `BRL::Bank` - for Brazilian bank account payments.\n- `NZD::Bank` - for New Zealand bank account payments.\n- `BWP::Bank` - for Botswana bank account payments.\n- `ZMW::Bank` - for Zambian bank account payments.\n- `CAD::Bank` - for Canadian bank account payments.\n- `UGX::Bank` - for Ugandan bank account payments.\n- `EGP::Bank` - for Egyptian bank account payments.\n- `EGP::Cash` - for Egyptian cash payments.\n",
"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"
}
},
"RecipientListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/Recipient"
}
},
"meta" : {
"$ref" : "#/components/schemas/PaginationMeta"
}
},
"readOnly" : true,
"example" : {
"object" : [ {
"created_at" : "2018-06-07T15:12:01.227Z",
"editable" : true,
"retriable" : true,
"id" : "b7432c2c-60bf-4a12-8a5f-71fa5818ecfd",
"input_usd_amount" : 1000,
"may_cancel" : true,
"metadata" : { },
"state" : "initial",
"transaction_id" : "3335836a-7828-4c54-9a8f-4c429036e580",
"transaction_state" : "initial",
"payout_method" : {
"id" : "a8d236df-4e11-4d7a-b395-d63762293b6b",
"type" : "XOF::Bank",
"details" : {
"last_name" : "English",
"first_name" : "Johnny",
"phone_number" : "+221752403639"
},
"metadata" : {
"my" : "data"
},
"fields" : {
"email" : {
"type" : "input",
"validations" : {
"format" : "\\A((\\w+([\\-+.]\\w+)*@[a-zA-Z0-9]+([\\-\\.][a-zA-Z0-9]+)*)*){3,320}\\z"
}
},
"first_name" : {
"type" : "input",
"validations" : {
"presence" : true
}
},
"last_name" : {
"type" : "input",
"validations" : {
"presence" : true
}
},
"phone_number" : {
"type" : "input",
"validations" : {
"presence" : true,
"invalid" : true
}
}
}
},
"exchange_rate" : 0.17361,
"fee_fractional" : 251300170,
"requested_amount" : 173.61,
"requested_currency" : "XOF",
"input_amount" : 1000,
"input_currency" : "UGX",
"output_amount" : 173.61,
"output_currency" : "XOF"
} ],
"meta" : {
"pagination" : {
"current_page" : 1,
"total_pages" : 1,
"total_count" : 1
}
}
}
},
"RecipientResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/Recipient"
}
},
"readOnly" : true,
"example" : {
"object" : {
"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" : {
"type" : "NGN::Bank",
"details" : {
"bank_code" : "058",
"bank_account" : "123456789",
"bank_account_type" : "10",
"last_name" : "English",
"first_name" : "Johnny"
},
"metadata" : {
"my" : "data"
},
"errors" : {
"address" : [ {
"error" : "invalid"
} ]
}
},
"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",
"errors" : {
"payout_method.address" : [ {
"error" : "invalid"
} ],
"input_currency" : [ {
"error" : "blank"
} ]
}
}
}
},
"RecipientRequest" : {
"type" : "object",
"properties" : {
"recipient" : {
"$ref" : "#/components/schemas/Recipient"
}
},
"example" : {
"recipient" : {
"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"
}
}
},
"ProofOfPaymentListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/ProofOfPayment"
}
}
},
"readOnly" : true,
"example" : {
"object" : [ {
"thumbnail" : "https://bitpesa-development-reports.s3.eu-west-1.amazonaws.com/my_file_thumb.jpg",
"file_name" : "my_file.jpg",
"id" : "id",
"url" : "https://bitpesa-development-reports.s3.eu-west-1.amazonaws.com/my_file.jpg"
}, {
"thumbnail" : "https://bitpesa-development-reports.s3.eu-west-1.amazonaws.com/my_file_thumb.jpg",
"file_name" : "my_file.jpg",
"id" : "id",
"url" : "https://bitpesa-development-reports.s3.eu-west-1.amazonaws.com/my_file.jpg"
} ]
}
},
"SenderListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/Sender"
}
},
"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" : [ {
"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"
}, {
"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"
} ]
}
},
"SenderRequest" : {
"type" : "object",
"properties" : {
"sender" : {
"$ref" : "#/components/schemas/Sender"
}
},
"example" : {
"sender" : {
"country" : "UG",
"phone_number" : "+256752403639",
"email" : "example@home.org",
"first_name" : "Johnny",
"last_name" : "English",
"city" : "Kampala",
"street" : "Unknown 17-3",
"address_description" : "Description of address",
"postal_code" : "798983",
"birth_date" : "1900-12-31",
"documents" : [ ],
"ip" : "127.0.0.1",
"identification_number" : "AB123456",
"identification_type" : "ID",
"lang" : "en",
"external_id" : "806ec63a-a5a7-43cc-9d75-1ee74fbcc026",
"city_of_birth" : "London",
"country_of_birth" : "GB",
"gender" : "M",
"metadata" : { }
}
}
},
"SenderResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/Sender"
},
"meta" : {
"$ref" : "#/components/schemas/SenderResponseMeta"
}
},
"readOnly" : true,
"example" : {
"meta" : {
"existing" : {
"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"
}
}
},
"object" : {
"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"
}
}
},
"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"
} ]
}
} ]
}
},
"ErrorStatus" : {
"type" : "object",
"properties" : {
"status" : {
"type" : "integer",
"readOnly" : true
},
"error" : {
"type" : "string",
"readOnly" : true
}
},
"readOnly" : true
},
"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"
}
}
},
"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"
}
}
}
}
},
"PayinMethodRequest" : {
"type" : "object",
"properties" : {
"payin_method" : {
"$ref" : "#/components/schemas/PayinMethod"
}
},
"example" : {
"payin_method" : {
"type" : "PayinMethod::NGN::Bank"
}
}
},
"WebhookDefinitionListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/WebhookDefinition"
}
},
"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" : { },
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "http://webhook.site/webhooks",
"events" : [ "transaction.paid_in", "transaction.paid_in" ],
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
}
}, {
"metadata" : { },
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "http://webhook.site/webhooks",
"events" : [ "transaction.paid_in", "transaction.paid_in" ],
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
}
} ]
}
},
"WebhookDefinitionRequest" : {
"type" : "object",
"properties" : {
"webhook" : {
"$ref" : "#/components/schemas/WebhookDefinition"
}
},
"example" : {
"webhook" : {
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "https://webhook.site/webhooks",
"events" : [ "transaction.paid_out" ],
"metadata" : { }
}
}
},
"WebhookDefinitionResponse" : {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/WebhookDefinition"
}
},
"readOnly" : true,
"example" : {
"object" : {
"url" : "https://webhook.site/webhooks",
"events" : [ "transaction.paid_out" ],
"metadata" : { },
"errors" : {
"url" : [ {
"error" : "invalid"
} ]
}
}
}
},
"RecipientWebhook" : {
"readOnly" : true,
"allOf" : [ {
"$ref" : "#/components/schemas/Webhook"
}, {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/Recipient"
}
},
"readOnly" : true
} ]
},
"Webhook" : {
"required" : [ "event", "object", "webhook" ],
"type" : "object",
"properties" : {
"webhook" : {
"type" : "string",
"description" : "The ID of the webhook that was used to send out this callback",
"format" : "uuid",
"readOnly" : true,
"example" : "b2f574ff-7efe-4579-9f16-fcb9097e5ab6"
},
"event" : {
"type" : "string",
"description" : "The event that triggered this webhook",
"readOnly" : true,
"example" : "transaction.paid"
},
"object" : {
"type" : "object",
"description" : "The returned object"
}
},
"description" : "Whenever objects in the TransferZero API change state, we can optionally send the changed details to a pre-registered webhook address. Webhooks can be created either using the [developer portal](https://developers.transferzero.com), or using the [TransferZero API](#operations-tag-Webhooks).\n\nWhenever possible we prefer using webhooks to listen on events (for example when a transaction has been paid out) instead of polling the status, and we expect implementations fully utilising webhooks.\n\nWebhooks will always generate a `POST` request to the specified endpoint, and will also include the same authentication headers as described in the [authentication documentation](https://docs.transferzero.com/docs/authentication), so their validity can be verified on the receiver end.",
"readOnly" : true,
"externalDocs" : {
"description" : "Webhooks in the API guide",
"url" : "https://docs.transferzero.com/docs/architecture/#webhooks"
}
},
"TransactionWebhook" : {
"readOnly" : true,
"allOf" : [ {
"$ref" : "#/components/schemas/Webhook"
}, {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/Transaction"
}
},
"readOnly" : true
} ]
},
"SenderWebhook" : {
"readOnly" : true,
"allOf" : [ {
"$ref" : "#/components/schemas/Webhook"
}, {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/Sender"
}
},
"readOnly" : true
} ]
},
"DocumentWebhook" : {
"readOnly" : true,
"allOf" : [ {
"$ref" : "#/components/schemas/Webhook"
}, {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/Document"
}
},
"readOnly" : true
} ]
},
"PayoutMethodWebhook" : {
"readOnly" : true,
"allOf" : [ {
"$ref" : "#/components/schemas/Webhook"
}, {
"type" : "object",
"properties" : {
"object" : {
"$ref" : "#/components/schemas/PayoutMethod"
}
},
"readOnly" : true
} ]
},
"WebhookDefinitionEventListResponse" : {
"type" : "object",
"properties" : {
"object" : {
"type" : "array",
"readOnly" : true,
"items" : {
"type" : "string",
"example" : "transaction.paid_in"
}
}
},
"readOnly" : true,
"example" : {
"object" : [ "transaction.paid_in", "recipient.paid_out", "recipient.error", "recipient.refunded", "transaction.paid_out", "transaction.refunded", "transaction.approved", "transaction.mispaid", "transaction.exception", "transaction.canceled", "sender.rejected", "sender.approved", "transaction_request.created", "transaction_request.accepted", "transaction_request.rejected", "transaction_request.modified", "transaction_request.confirmed", "transaction_request.canceled", "transaction_request.reset", "transaction_request.refused", "transaction_request.expired", "transaction.created", "payout_method.created", "payout_method.disabled", "sender.created", "sender.disabled", "document.created", "document.disabled" ]
}
},
"Account" : {
"properties" : {
"amount" : {
"type" : "number",
"description" : "The account balance for the given currency",
"readOnly" : true,
"example" : 1000.0
},
"currency" : {
"type" : "string",
"description" : "The currency of this balance",
"readOnly" : true,
"example" : "USD"
},
"amount_after_pending" : {
"type" : "number",
"description" : "Represents the account balance after deducting pending transactions from the last 7 days. It provides a more accurate depiction of available funds.",
"readOnly" : true,
"example" : 1000.0
}
},
"readOnly" : true,
"example" : {
"amount" : 1000.0,
"amount_after_pending" : 1000.0,
"currency" : "USD"
}
},
"AccountMeta" : {
"type" : "object",
"properties" : {
"negative_balance" : {
"type" : "boolean",
"description" : "Indicates whether account balances are permitted to be debited below zero",
"readOnly" : true,
"example" : false
}
},
"readOnly" : true,
"example" : {
"negative_balance" : false
}
},
"DebitRequest" : {
"type" : "object",
"properties" : {
"debit" : {
"$ref" : "#/components/schemas/Debit"
}
}
},
"DebitListRequest" : {
"type" : "object",
"properties" : {
"debit" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Debit"
}
}
}
},
"Debit" : {
"required" : [ "to_id", "to_type" ],
"type" : "object",
"properties" : {
"amount" : {
"type" : "number",
"description" : "The amount to be debited from your account.\n\nThe \"amount\" parameter is optional -\n- if included, it must equal the amount required to fund the transaction.\n- if omitted, it will default to the amount required to fund the transaction.\n",
"format" : "double",
"example" : 10000
},
"currency" : {
"type" : "string",
"description" : "The currency of the amount in 3-character alpha ISO 4217 currency format.\n\nThe \"currency\" parameter is optional\n- if omitted, it will default to the payin currency of the transaction.\n- it can be added in as an additional check to ensure that the expected currency is used. (an error will be given back if it does not match up with the payin currency of the transaction)\n",
"example" : "NGN"
},
"to_type" : {
"type" : "string",
"description" : "Describes what the debit is funding",
"example" : "Transaction"
},
"to_id" : {
"type" : "string",
"description" : "The ID of the resource the debit is funding",
"format" : "uuid",
"example" : "5f44026b-7904-4c30-87d6-f8972d790ded"
},
"metadata" : {
"type" : "object",
"description" : "Metadata of account debit",
"example" : { }
},
"id" : {
"type" : "string",
"format" : "uuid",
"readOnly" : true,
"example" : "5f44026b-7904-4c30-87d6-f8972d790ded"
},
"created_at" : {
"type" : "string",
"description" : "Date and time that the debit was created",
"format" : "date-time",
"readOnly" : true
},
"usd_amount" : {
"type" : "number",
"description" : "The amount to be debited from your account converted to USD\n",
"format" : "double",
"readOnly" : true,
"example" : 200.06211683187206
},
"running_balance" : {
"type" : "number",
"description" : "The total amount remaining in your account after the debit call\n",
"format" : "double",
"readOnly" : true,
"example" : 2000000
},
"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" : "Debits are used to fund transactions from your internal TransferZero balance.",
"example" : {
"to_type" : "Transaction",
"amount" : 10000,
"metadata" : { },
"to_id" : "5f44026b-7904-4c30-87d6-f8972d790ded",
"created_at" : "2000-01-23T04:56:07.000+00:00",
"currency" : "NGN",
"id" : "5f44026b-7904-4c30-87d6-f8972d790ded",
"running_balance" : 2000000,
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
},
"usd_amount" : 200.06211683187206
},
"externalDocs" : {
"description" : "Funding Transactions in the API Guide",
"url" : "https://docs.transferzero.com/docs/transaction-flow/#funding-transactions"
}
},
"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
}
}
},
"PayoutMethodMobileProviderEnum" : {
"type" : "string",
"description" : "The Mobile Wallet provider of the recipient:\n\nFor XOF (Senegal) valid options are:\n- `orange`: Orange\n- `tigo`: Tigo\n- `emoney`: Emoney\n- `free`: Free\n- `expresso` : Expresso\n- `wave`: Wave\n\nFor XOF (Ivory Coast) valid options are:\n- `orange`: Orange\n- `moov`: Moov\n- `mtn`: MTN\n- `wave`: Wave\n\nFor XOF (Burkina Faso) valid options are:\n- `orange`: Orange\n- `mobicash`: Mobicash\n- `moov` : Moov\n\nFor XOF (Togo) valid options are:\n- `moov`: Moov\n- `tmoney`: Tmoney\n\nFor XOF (Benin) valid options are:\n- `moov`: Moov\n- `mtn`: Mtn\n\nFor XOF (Mali) valid options are:\n- `orange`: Orange\n- `mobicash`: Mobicash\n- `tigo` : Tigo\n\nFor GHS valid options are:\n- `airteltigo`: AirtelTigo\n- `mtn`: MTN\n- `vodafone`: Vodafone\n\nFor KES valid options are:\n- `mpesa`: MPESA\n\nFor UGX valid options are:\n- `africell`: Africell\n- `airtel`: Airtel\n- `mtn`: MTN\n- `telecom`: Telecom\n\nFor XAF (Chad) valid options are:\n- `moov`: Moov\n\nFor XAF (Cameroon) valid options are:\n- `orange`: Orange\n- `mtn`: MTN\n\nFor XAF (Congo) valid options are:\n- `airtel`: Airtel\n- `mtn`: MTN\n\nFor XAF (Gabon) valid options are:\n- `airtel`: Airtel\n- `moov`: Moov\n\nFor GNF (Guinea) valid options are:\n- `orange`: Orange\n- `mtn`: MTN",
"example" : "orange",
"enum" : [ "africell", "airtel", "airteltigo", "emoney", "expresso", "free", "mobicash", "moov", "mpesa", "mtn", "orange", "telecom", "tigo", "tmoney", "vodafone", "wave" ]
},
"AccountValidationResult" : {
"type" : "object",
"properties" : {
"account_name" : {
"type" : "string",
"readOnly" : true,
"example" : "John Smith"
},
"mapped_mobile_provider" : {
"type" : "string",
"readOnly" : true,
"example" : "mtn"
},
"account_status" : {
"type" : "string",
"readOnly" : true,
"example" : "active"
}
},
"description" : "Describes the account holder name on a successful match",
"readOnly" : true
},
"AccountValidationError" : {
"type" : "object",
"properties" : {
"error" : {
"type" : "string",
"readOnly" : true,
"example" : "Could not find account"
}
},
"description" : "Describes the error message on an unsuccessful match",
"readOnly" : true
},
"ApiLog" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "string",
"description" : "ID of the API log",
"format" : "uuid",
"readOnly" : true,
"example" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"request_method" : {
"type" : "string",
"description" : "Initial HTTP request method",
"readOnly" : true,
"example" : "POST"
},
"request_url" : {
"type" : "string",
"description" : "URL to which initial request was sent",
"readOnly" : true,
"example" : "https://api.transferzero/v1/transactions/validate"
},
"request_body" : {
"type" : "string",
"description" : "Body sent with initial request returned as a string",
"readOnly" : true,
"example" : "{\"message\":\"Email dispatched: Accepted (user@transferzero.com)\"}"
},
"request_headers" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
},
"description" : "Authorization and access information sent with initial request",
"readOnly" : true,
"example" : {
"HTTP_VERSION" : "HTTP/1.1",
"HTTP_ACCEPT" : "application/json",
"HTTP_USER_AGENT" : "TransferZero Ruby",
"HTTP_AUTHORIZATION_NONCE" : "0000",
"HTTP_AUTHORIZATION_KEY" : "0000",
"HTTP_AUTHORIZATION_SIGNATURE" : "0000",
"HTTP_CONNECTION" : "close",
"HTTP_HOST" : "localhost:3002"
}
},
"response_status" : {
"type" : "string",
"description" : "Status of response",
"readOnly" : true,
"example" : "200"
},
"response_body" : {
"type" : "string",
"description" : "Full response body returned as a string",
"readOnly" : true,
"example" : "{\"object\":{\"result\":0}}"
},
"response_headers" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
},
"description" : "Headers returned with response",
"readOnly" : true,
"example" : {
"X-Frame-Options" : "SAMEORIGIN",
"X-XSS-Protection" : "1; mode=block",
"X-Content-Type-Options" : "nosniff",
"Content-Type" : "application/json; charset=UTF-8"
}
},
"created_at" : {
"type" : "string",
"description" : "Date and time of response",
"readOnly" : true,
"example" : "2019-01-11T00:00:00.001+0000"
}
},
"description" : "The response object returned with requests to access individual API logs\n",
"readOnly" : true,
"example" : {
"response_headers" : {
"X-Frame-Options" : "SAMEORIGIN",
"X-XSS-Protection" : "1; mode=block",
"X-Content-Type-Options" : "nosniff",
"Content-Type" : "application/json; charset=UTF-8"
},
"request_body" : "{\"message\":\"Email dispatched: Accepted (user@transferzero.com)\"}",
"response_status" : "200",
"request_headers" : {
"HTTP_VERSION" : "HTTP/1.1",
"HTTP_ACCEPT" : "application/json",
"HTTP_USER_AGENT" : "TransferZero Ruby",
"HTTP_AUTHORIZATION_NONCE" : "0000",
"HTTP_AUTHORIZATION_KEY" : "0000",
"HTTP_AUTHORIZATION_SIGNATURE" : "0000",
"HTTP_CONNECTION" : "close",
"HTTP_HOST" : "localhost:3002"
},
"response_body" : "{\"object\":{\"result\":0}}",
"created_at" : "2019-01-11T00:00:00.001+0000",
"id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"request_method" : "POST",
"request_url" : "https://api.transferzero/v1/transactions/validate"
}
},
"DlocalBalance" : {
"properties" : {
"currency" : {
"type" : "string",
"description" : "The currency of this balance",
"readOnly" : true,
"example" : "USD"
},
"available_balance" : {
"type" : "number",
"description" : "The available balance for the given currency",
"readOnly" : true,
"example" : 1000
},
"previous_day_closing_balance" : {
"type" : "number",
"description" : "The balance at end of previous day",
"readOnly" : true,
"example" : 1000
},
"current_balance_date" : {
"type" : "string",
"description" : "Current date",
"readOnly" : true,
"example" : "2026-02-24"
}
},
"readOnly" : true,
"example" : {
"current_balance_date" : "2026-02-24",
"currency" : "USD",
"available_balance" : 1000,
"previous_day_closing_balance" : 1000
}
},
"Currency" : {
"type" : "object",
"properties" : {
"code" : {
"type" : "string",
"description" : "The currency code in 3-character alpha ISO 4217 currency format",
"readOnly" : true,
"example" : "NGN"
},
"name" : {
"type" : "string",
"description" : "Name of currency",
"readOnly" : true,
"example" : "Nigerian Naira"
},
"symbol" : {
"type" : "string",
"description" : "Symbol of currency",
"readOnly" : true,
"example" : "₦"
},
"decimals" : {
"type" : "number",
"description" : "Number of decimal points",
"readOnly" : true,
"example" : 2
},
"subunit_to_unit" : {
"type" : "string",
"description" : "Subunits in Unit (eg. there are 100 cents in 1 US Dollar)",
"readOnly" : true,
"example" : "100"
},
"primary" : {
"type" : "boolean",
"description" : "Is this a primary currency?",
"readOnly" : true,
"example" : true
},
"min" : {
"type" : "string",
"description" : "The minimum amount allowed in a transaction",
"readOnly" : true,
"example" : "100"
},
"max" : {
"type" : "string",
"description" : "The maximum amount allowed in a transaction",
"readOnly" : true,
"example" : "50000000"
},
"usd_equivalent" : {
"type" : "string",
"description" : "The equivalent of the currency to 1 USD",
"readOnly" : true
}
},
"readOnly" : true
},
"CurrencyExchange" : {
"allOf" : [ {
"$ref" : "#/components/schemas/Currency"
}, {
"type" : "object",
"properties" : {
"opposites" : {
"type" : "array",
"description" : "Lists the currencies where you can exchange from this one",
"readOnly" : true,
"items" : {
"$ref" : "#/components/schemas/CurrencyOpposite"
}
}
},
"readOnly" : true
} ]
},
"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"
}
},
"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
}
}
}
}
},
"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"
}
}
},
"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)"
}
}
}
},
"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
}
}
},
"WebhookLog" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "string",
"description" : "ID of the webhook log",
"readOnly" : true,
"example" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"message" : {
"type" : "string",
"description" : "Message detailing webhook event",
"readOnly" : true,
"example" : "Transaction(a0696374-de2f-4b4e-a2d7-cb4e0a1240c0) transaction.mispaid pending!"
},
"metadata" : {
"$ref" : "#/components/schemas/WebhookLogMetadata"
},
"created_at" : {
"type" : "string",
"description" : "Date and time of response",
"readOnly" : true,
"example" : "2018-12-31T23:59:50.059+0000"
},
"parent_id" : {
"type" : "string",
"readOnly" : true,
"example" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"parent_type" : {
"type" : "string",
"readOnly" : true,
"example" : "Webhook"
}
},
"readOnly" : true,
"example" : {
"metadata" : {
"tries" : 15,
"request" : {
"headers" : {
"Content-Type" : "application/json",
"Authorization-Nonce" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Key" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Signature" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Accept-Encoding" : "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
"Accept" : "*/*",
"User-Agent" : "Ruby",
"Host" : "localhost:3000",
"Content-Length" : "3549"
},
"body" : "{\"webhook\":\"54cbd6f2-b920-41e9-a225-b1000e024787\",\"event\":\"transaction.mispaid\",\"object\":{\"id\":\"cbcea909-85e3-448f-bd07-b9ecdff6e971\"}}",
"url" : "http://localhost:3000"
},
"instance_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"response" : {
"headers" : {
"date" : "Fri, 11 Jan 2019 09:00:00 GMT",
"connection" : "close",
"content-type" : "text/html; charset=utf-8",
"x-web-console-session-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-web-console-mount-point" : "/__web_console",
"x-request-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-runtime" : "0.484015",
"content-length" : "145453"
},
"body" : " Action Controller: Exception caught",
"status" : "500"
},
"attempt_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"params" : {
"metadata" : { },
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "http://webhook.site/webhooks",
"events" : [ "transaction.paid_in", "transaction.paid_in" ],
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
}
},
"event" : "transaction.mispaid",
"instance_type" : "Transaction",
"app_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"api_key_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"parent_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"created_at" : "2018-12-31T23:59:50.059+0000",
"id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"message" : "Transaction(a0696374-de2f-4b4e-a2d7-cb4e0a1240c0) transaction.mispaid pending!",
"parent_type" : "Webhook"
}
},
"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"
}
},
"ValidationErrors" : {
"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"
} ]
}
},
"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```"
},
"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```"
},
"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```"
},
"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"
} ]
},
"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.\nIf 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)\n",
"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.\nThis 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"
}
},
"RecipientStateReasonDetails" : {
"anyOf" : [ {
"$ref" : "#/components/schemas/StateReasonDetails"
} ]
},
"RecipientState" : {
"type" : "string",
"description" : "The state of the recipient. Can be one of the following:\n\n* `initial`: We haven't initiated the payout yet, you can still cancel the transaction\n* `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.\n* `success`: Payout is done, and the recipient has been paid.\n* `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.\n* `refunded`: You asked us to cancel the transaction and we refunded the money.\n* `manual`: There were too many errors on this transaction, and we stopped retrying. Please edit the recipient, contact us or cancel the transaction.\n* `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.\n* `overpaid`: The recipient was paid out more than was requested (not applicable for most of the payout providers)\n* `canceled`: The transaction has been cancelled, and we will refund the money soon\n* `exception`: Some exception has happened; please contact TransferZero",
"readOnly" : true,
"example" : "initial",
"enum" : [ "initial", "pending", "success", "error", "refunded", "manual", "stuck", "overpaid", "canceled", "exception" ]
},
"ProofOfPayment" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "string",
"description" : "UUID of the uploaded document"
},
"file_name" : {
"type" : "string",
"description" : "Name of the uploaded file",
"example" : "my_file.jpg"
},
"thumbnail" : {
"type" : "string",
"description" : "URL to thumbnail image of the uploaded file",
"example" : "https://bitpesa-development-reports.s3.eu-west-1.amazonaws.com/my_file_thumb.jpg"
},
"url" : {
"type" : "string",
"description" : "URL to uploaded file",
"example" : "https://bitpesa-development-reports.s3.eu-west-1.amazonaws.com/my_file.jpg"
}
},
"example" : {
"thumbnail" : "https://bitpesa-development-reports.s3.eu-west-1.amazonaws.com/my_file_thumb.jpg",
"file_name" : "my_file.jpg",
"id" : "id",
"url" : "https://bitpesa-development-reports.s3.eu-west-1.amazonaws.com/my_file.jpg"
}
},
"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)\n",
"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:\n\n- `DL`: Driving License\n- `PP`: International Passport\n- `ID`: National ID\n- `OT`: Other\n\nPlease note for Wizall `XOF::Cash` transactions the valid options are:\n- `ID`: National ID\n- `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\n(for example the local ID of the sender on your end). When requesting sender details you will receive the\nsent 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:\n\n- `M`: Male\n- `F`: Female\n- `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"
}
},
"SenderState" : {
"type" : "string",
"description" : "The state of the sender. Can be one of the following:\n\n- `incomplete`: When a sender has not submitted required details or documents (cannot transact)\n- `initial`: When a sender is created and has not been through any KYC checking (cannot transact)\n- `verified`: A sender has passed sanction list checks (cannot transact)\n- `approved`: The sender has passed both KYC and sanction checks (can transact)\n- `banned`: An admin has banned the sender (cannot transact)\n- `rejected`: The sender has failed sanction list checks (cannot transact)\n- `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" ]
},
"SenderResponseMeta" : {
"type" : "object",
"properties" : {
"existing" : {
"$ref" : "#/components/schemas/SenderResponseExisting"
}
},
"readOnly" : true,
"example" : {
"existing" : {
"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"
}
}
}
},
"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.\n\nFor 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\nrecipients, usually one is provided.\n",
"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/"
}
},
"TransactionState" : {
"type" : "string",
"description" : "The state of the transaction, which can be one of the following:\n\n* `initial`: Transaction is created, but not yet ready to receive payments (waiting for Sender to be KYC'd and approved).\n* `approved`: Transaction is created and the sender is approved. Payment can be received\n* `pending`: There's an active collection to fund the transaction that needs to clear.\n* `received`: Transaction has received the correct payin amount and will start processing the payouts.\n* `mispaid`: Transaction received funds, but not the requested amount. The transaction will be resized, and will start payout based on the received funds.\n* `manual`: Some of the payments to the recipients have run into issues. Please check the recipient statuses for more information.\n* `paid`: Transaction has received correct payins and has performed payouts to all recipients. No further steps required\n* `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.\n* `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.\n* `processing`: Transaction has received a payin, it's processing.\n* `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" ]
},
"TransactionResponseMeta" : {
"type" : "object",
"properties" : {
"existing" : {
"$ref" : "#/components/schemas/TransactionResponseExisting"
}
},
"readOnly" : true
},
"WebhookDefinition" : {
"required" : [ "events", "url" ],
"type" : "object",
"properties" : {
"url" : {
"type" : "string",
"description" : "The URL to receive the webhook",
"example" : "http://webhook.site/webhooks"
},
"events" : {
"type" : "array",
"description" : "A list of events to subscribe to",
"items" : {
"type" : "string",
"example" : "transaction.paid_in"
}
},
"metadata" : {
"type" : "object",
"example" : { }
},
"id" : {
"type" : "string",
"description" : "The ID of the webhook",
"readOnly" : true,
"example" : "1cd580b2-2a1b-4f73-81c8-0308308baef2"
},
"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" : "Object that holds where to send webhooks, and what events should it be triggered with",
"example" : {
"metadata" : { },
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "http://webhook.site/webhooks",
"events" : [ "transaction.paid_in", "transaction.paid_in" ],
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
}
},
"externalDocs" : {
"description" : "Webhooks in the API guide",
"url" : "https://docs.transferzero.com/docs/architecture/#webhooks"
}
},
"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
}
},
"CurrencyOpposite" : {
"allOf" : [ {
"$ref" : "#/components/schemas/Currency"
}, {
"type" : "object",
"properties" : {
"rate" : {
"type" : "number",
"description" : "The rate of this particular currency with the base one",
"readOnly" : true
},
"mtm_rate" : {
"type" : "number",
"description" : "Mark to market rate of this particular currency against the base one with the margin factored in",
"readOnly" : true
},
"margin" : {
"type" : "string",
"description" : "The margin set for transactions of this particular currency with the base one",
"readOnly" : true
}
},
"readOnly" : true
} ]
},
"WebhookLogMetadata" : {
"type" : "object",
"properties" : {
"params" : {
"$ref" : "#/components/schemas/WebhookDefinition"
},
"event" : {
"type" : "string",
"description" : "Specific event that triggered the webhook",
"readOnly" : true,
"example" : "transaction.mispaid"
},
"instance_id" : {
"type" : "string",
"description" : "Instance ID of the webhook event",
"readOnly" : true,
"example" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"instance_type" : {
"type" : "string",
"description" : "Type of instance event",
"readOnly" : true,
"example" : "Transaction"
},
"attempt_id" : {
"type" : "string",
"description" : "Attempt ID",
"readOnly" : true,
"example" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"tries" : {
"type" : "integer",
"description" : "Number of tries at the point webhook was triggered",
"readOnly" : true,
"example" : 15
},
"request" : {
"$ref" : "#/components/schemas/WebhookLogMetadataRequest"
},
"response" : {
"$ref" : "#/components/schemas/WebhookLogMetadataResponse"
},
"app_id" : {
"type" : "string",
"description" : "ID of app on which webhook event was triggered",
"readOnly" : true,
"example" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
},
"api_key_id" : {
"type" : "string",
"description" : "ID of API key in use at point of webhook event",
"readOnly" : true,
"example" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
}
},
"example" : {
"tries" : 15,
"request" : {
"headers" : {
"Content-Type" : "application/json",
"Authorization-Nonce" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Key" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Signature" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Accept-Encoding" : "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
"Accept" : "*/*",
"User-Agent" : "Ruby",
"Host" : "localhost:3000",
"Content-Length" : "3549"
},
"body" : "{\"webhook\":\"54cbd6f2-b920-41e9-a225-b1000e024787\",\"event\":\"transaction.mispaid\",\"object\":{\"id\":\"cbcea909-85e3-448f-bd07-b9ecdff6e971\"}}",
"url" : "http://localhost:3000"
},
"instance_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"response" : {
"headers" : {
"date" : "Fri, 11 Jan 2019 09:00:00 GMT",
"connection" : "close",
"content-type" : "text/html; charset=utf-8",
"x-web-console-session-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-web-console-mount-point" : "/__web_console",
"x-request-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-runtime" : "0.484015",
"content-length" : "145453"
},
"body" : " Action Controller: Exception caught",
"status" : "500"
},
"attempt_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"params" : {
"metadata" : { },
"id" : "1cd580b2-2a1b-4f73-81c8-0308308baef2",
"url" : "http://webhook.site/webhooks",
"events" : [ "transaction.paid_in", "transaction.paid_in" ],
"errors" : {
"phone_number" : [ {
"error" : "invalid"
} ],
"documents" : [ {
"error" : "blank"
} ]
}
},
"event" : "transaction.mispaid",
"instance_type" : "Transaction",
"app_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"api_key_id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0"
}
},
"PayoutMethodCountryEnum" : {
"type" : "string",
"description" : "The country for the pickup or mobile payout.\n\nFor USD cash pickup in Nigeria, valid options are:\n- `NG`: Nigeria\n\nFor XOF cash pickup, valid options are:\n- `CI`: Ivory Coast\n- `ML`: Mali\n- `SN`: Senegal\n\nFor XOF mobile payout, valid options are:\n- `BJ`: Benin\n- `BF`: Burkina Faso\n- `CI`: Ivory Coast\n- `ML`: Mali\n- `SN`: Senegal\n- `TG`: Togo\n\nFor XAF mobile payout, valid options are:\n- `CG`: Congo\n- `CM`: Cameroon\n- `GA`: Gabon\n- `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" ]
},
"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"
},
"PayoutMethodBankAccountTypeEnum" : {
"type" : "string",
"description" : "The type of the bank account:\n\n- `10`: Savings account\n- `20`: Current account\n- `30`: Payment account\n- `40`: Salary account",
"example" : "10",
"enum" : [ "10", "20", "30", "40" ]
},
"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```"
},
"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```"
},
"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",
"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" ]
},
"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"
},
"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```"
},
"PayoutMethodCashProviderEnum" : {
"type" : "string",
"description" : "The cash provider for the pickup:\nFor XOF valid options are:\n- `wizall`: Wizall",
"example" : "wizall",
"enum" : [ "wari", "wizall" ]
},
"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"
},
"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```"
},
"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```"
},
"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```"
},
"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."
},
"PayoutMethodIdentityCardTypeEnum" : {
"type" : "string",
"description" : "The type of the identity card used by the sender or recipient:\n\n- `PP`: Passport\n- `ID`: National Identity Card\n- `O`: Other type of identity card\n- `DL`: Driving License\n- `OT`: Other type of identity card",
"example" : "PP",
"enum" : [ "O", "PP", "ID", "DL", "OT" ]
},
"PayoutMethodGenderEnum" : {
"type" : "string",
"description" : "The gender of the sender:\n\n- `M`: Male\n- `F`: Female",
"example" : "F",
"enum" : [ "M", "F" ]
},
"PayoutMethodDetailsBalance" : {
"type" : "object",
"properties" : {
"reference" : {
"type" : "string"
}
},
"description" : "```JSON\n\"details\": {\n \"reference\": \"Reference\" // optional\n}\n```"
},
"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}"
},
"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"
},
"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" ]
},
"PayoutMethodLegalEntityTypeEnum" : {
"type" : "string",
"description" : "The entity type of the recipient.\n\nFor ZAR personal payouts valid options are:\n- `person`: Person\n\nFor ZAR business payouts valid options are:\n- `sole_proprietorship`: Sole Proprietorship\n- `privately_owned_company`: Privately Owned Company (Limited Company)\n- `publicly_owned_company`: Publicly Owned Company (PLC)\n- `government_owned_entity`: Government Owned Entity Trusts\n- `partnership`: Partnership\n- `go`: GO (Majority Owned Subsidiary of State-Owned Company)\n- `financial_institution`: Financial Institution",
"example" : "person",
"enum" : [ "person", "sole_proprietorship", "privately_owned_company", "publicly_owned_company", "government_owned_entity", "partnership", "go", "financial_institution" ]
},
"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"
},
"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"
},
"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"
},
"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"
},
"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```"
},
"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"
},
"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```"
},
"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"
},
"PayoutMethodPixKeyTypeEnum" : {
"type" : "string",
"description" : "The type of pix key used by the recipient\n- `cpf`: Natural person register number\n- `cnpj`: Company registration number\n- `phone`: Phone number\n- `email`: Email address\n- `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"
},
"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"
},
"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"
},
"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"
},
"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"
},
"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"
},
"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}"
},
"PoliticallyExposedPerson" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer",
"readOnly" : true,
"example" : 1
},
"name" : {
"type" : "string",
"description" : "Full name of the politically exposed person\n",
"example" : "Ronald Reagan"
},
"position" : {
"type" : "string",
"description" : "The office held by the politically exposed person\n",
"example" : "President of the United States"
},
"started_date" : {
"type" : "string",
"description" : "The date on which the person started holding the office\n",
"format" : "date-time"
},
"ended_date" : {
"type" : "string",
"description" : "The date on which the person ended holding the office\n",
"format" : "date-time"
},
"sender_id" : {
"type" : "string",
"description" : "The ID of the Sender to whom the person is attached to\n",
"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
}
}
},
"SenderResponseExisting" : {
"type" : "object",
"properties" : {
"sender" : {
"$ref" : "#/components/schemas/Sender"
}
},
"readOnly" : true,
"example" : {
"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"
}
}
},
"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
}
},
"TransactionResponseExisting" : {
"type" : "object",
"properties" : {
"sender" : {
"$ref" : "#/components/schemas/Sender"
},
"transaction" : {
"$ref" : "#/components/schemas/Transaction"
}
},
"readOnly" : true
},
"WebhookLogMetadataRequest" : {
"type" : "object",
"properties" : {
"headers" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
},
"readOnly" : true,
"example" : {
"Content-Type" : "application/json",
"Authorization-Nonce" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Key" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Signature" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Accept-Encoding" : "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
"Accept" : "*/*",
"User-Agent" : "Ruby",
"Host" : "localhost:3000",
"Content-Length" : "3549"
}
},
"body" : {
"type" : "string",
"description" : "The body that was sent in the webhook",
"readOnly" : true,
"example" : "{\"webhook\":\"54cbd6f2-b920-41e9-a225-b1000e024787\",\"event\":\"transaction.mispaid\",\"object\":{\"id\":\"cbcea909-85e3-448f-bd07-b9ecdff6e971\"}}"
},
"url" : {
"type" : "string",
"description" : "Webhook URL",
"readOnly" : true,
"example" : "http://localhost:3000"
}
},
"description" : "Metadata related to the initial request that triggered the webhook",
"example" : {
"headers" : {
"Content-Type" : "application/json",
"Authorization-Nonce" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Key" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Authorization-Signature" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"Accept-Encoding" : "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
"Accept" : "*/*",
"User-Agent" : "Ruby",
"Host" : "localhost:3000",
"Content-Length" : "3549"
},
"body" : "{\"webhook\":\"54cbd6f2-b920-41e9-a225-b1000e024787\",\"event\":\"transaction.mispaid\",\"object\":{\"id\":\"cbcea909-85e3-448f-bd07-b9ecdff6e971\"}}",
"url" : "http://localhost:3000"
}
},
"WebhookLogMetadataResponse" : {
"type" : "object",
"properties" : {
"body" : {
"type" : "string",
"description" : "Full body of response",
"readOnly" : true,
"example" : " Action Controller: Exception caught"
},
"headers" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
},
"description" : "Headers delivered with webhook response",
"readOnly" : true,
"example" : {
"date" : "Fri, 11 Jan 2019 09:00:00 GMT",
"connection" : "close",
"content-type" : "text/html; charset=utf-8",
"x-web-console-session-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-web-console-mount-point" : "/__web_console",
"x-request-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-runtime" : "0.484015",
"content-length" : "145453"
}
},
"status" : {
"type" : "string",
"description" : "Status of response",
"readOnly" : true,
"example" : "500"
}
},
"description" : "Metadata related to the webhook response",
"example" : {
"headers" : {
"date" : "Fri, 11 Jan 2019 09:00:00 GMT",
"connection" : "close",
"content-type" : "text/html; charset=utf-8",
"x-web-console-session-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-web-console-mount-point" : "/__web_console",
"x-request-id" : "a0696374-de2f-4b4e-a2d7-cb4e0a1240c0",
"x-runtime" : "0.484015",
"content-length" : "145453"
},
"body" : " Action Controller: Exception caught",
"status" : "500"
}
}
},
"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"
}
}
}
}