openapi: 3.0.2 info: title: TransferZero Account Debits Payout Methods API description: Reference documentation for the TransferZero API V1 version: '1.0' servers: - url: https://api-sandbox.transferzero.com/v1 - url: https://api.transferzero.com/v1 security: - AuthorizationKey: [] AuthorizationNonce: [] AuthorizationSignature: [] - AuthorizationKey: [] AuthorizationSecret: [] tags: - name: Payout Methods paths: /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. Example: `/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. Example: `/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. Example: `/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 Allows filtering results by the specified `created_at` timeframe. Example: `/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 Allows filtering results by the specified `created_at` timeframe. Example: `/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. ' 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. Example: `/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. Example: `/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. Example: `/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. components: schemas: PayoutMethodDetailsMADCash: required: - first_name - last_name - phone_number - sender_identity_card_id - sender_identity_card_type type: object properties: first_name: type: string last_name: type: string phone_number: type: string sender_identity_card_type: $ref: '#/components/schemas/PayoutMethodIdentityCardTypeEnum' sender_identity_card_id: type: string sender_city_of_birth: type: string sender_country_of_birth: type: string sender_gender: $ref: '#/components/schemas/PayoutMethodGenderEnum' reason: type: string identity_card_type: $ref: '#/components/schemas/PayoutMethodIdentityCardTypeEnum' identity_card_id: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+212537718685\"\n # Mandatory; E.164 international format\n \"sender_identity_card_type\" => \"O\",\n # Mandatory; Values: \"O\": Other, \"PP\": Passport, \"ID\": National ID\n \"sender_identity_card_id\" => 'AB12345678',\n # Mandatory\n \"sender_city_of_birth\" => \"London\",\n # Optional\n \"sender_country_of_birth\" => \"GB\",\n # Optional; ISO 2-letter format\n \"sender_gender\" => \"M\",\n # Optional; Values: \"M\": Male, \"F\": Female\n \"reason\" => \"Remittance payment\",\n # Optional; Default value is 'Remittance payment'\n \"identity_card_type\" => \"ID\",\n # Optional; Values: \"PP\": Passport, \"ID\": National ID\n \"identity_card_id\" => 'AB12345678'\n # Optional\n}\n```\n\nPlease note when sending MAD::Cash payments you should subscribe to the recipient.pending webhook, as that will broadcast the payment reference ID the customer need to use to obtain the funds.\nExample webhook response excerpt -\n\n```JSON\n{\n (...)\n \"state\":\"pending\",\n \"metadata\": {\n \"payment_reference\":\"9M5GJRJUBCY\"\n },\n (...)\n}\n```\n\nThe reference can also be provided optionally for MAD::Cash, but if you want to use this functionality please contact us for more details." PayoutMethodDetailsXAFBank: required: - first_name - iban - last_name type: object properties: first_name: type: string last_name: type: string iban: type: string bank_account: type: string bank_name: type: string bank_country: type: string bank_code: type: string sort_code: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"iban\": \"CM2110033052090901100045910\", # IBAN format\n \"bank_account\": \"09011000459\",\n \"bank_name\": \"United Bank for Africa - Cameroon\",\n \"bank_country\": \"CM\", # ISO country code for Cameroon\n \"bank_code\": \"10033\",\n \"sort_code\": \"10\",\n \"transfer_reason\": \"personal_account\"\n}\n```\n\nSee [XAF Bank](https://docs.transferzero.com/docs/payout-details/#xafbank) documentation for the bank_code and transfer_reason lists" PayoutMethodDetailsGBPBank: required: - first_name - last_name type: object properties: first_name: type: string last_name: type: string iban: type: string bank_account: type: string sort_code: type: string bic: type: string bank_name: type: string narration: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"iban\": \"GB45LOYD60161331926819\", // Required if no `bank_account` and `sort_code`\n \"bank_account\": \"12345678\", // Required if `iban` is not present\n \"sort_code\": \"123456\", // Required if `bank_account` is present\n \"bic\": \"CHASUS33XXX\" // Optional\n \"bank_name\": \"JPMorgan Chase Bank\", // Optional\n \"narration\": \"Birthday Gift\" // Optional\n}\n```" PayoutMethodDetailsCADBank: required: - bank_account - bank_code - branch_code - first_name - last_name type: object properties: first_name: type: string last_name: type: string bank_account: type: string bank_code: type: string branch_code: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_account\": \"123456789\",\n \"bank_code\": \"003\",\n \"branch_code\": \"12345\"\n}\n```\nSee [CAD Bank](https://docs.transferzero.com/docs/payout-details/#cadbank) documentation for the bank_code list" PayoutMethodDetailsBRLBank: required: - city - first_name - identity_card_id - last_name - postal_code - transfer_reason type: object properties: first_name: type: string last_name: type: string city: type: string postal_code: type: string phone_number: type: string bank_code: type: string branch_code: type: string bank_account: type: string bank_account_type: $ref: '#/components/schemas/PayoutMethodBankAccountTypeEnum' pix_key_type: $ref: '#/components/schemas/PayoutMethodPixKeyTypeEnum' pix_key_value: type: string identity_card_id: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' birth_date: type: string description: Date of birth of recipient format: date description: "PIX Payment:\n```JSON\n \"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"city\": \"Brasilia\",\n \"postal_code\": \"70070\",\n \"phone_number\": \"+552112345678\", // E.164 international format\n \"pix_key_type\": \"email\",\n \"pix_key_value\": \"person@example.com\",\n \"identity_card_id\": \"01234567890\", // CPF or CNPJ\n \"transfer_reason\": \"personal_account\"\n }\n```\n\nTED Payment:\n```JSON\n \"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"city\": \"Brasilia\",\n \"postal_code\": \"70070\",\n \"phone_number\": \"+552112345678\", // E.164 international format\n \"bank_code\": \"104\",\n \"branch_code\": \"00001\",\n \"bank_account\": \"0009795493\",\n \"bank_account_type\": \"10\",\n \"identity_card_id\": \"01234567890\", // CPF or CNPJ\n \"transfer_reason\": \"personal_account\"\n }\n```\n\nSee [BRL Bank](https://docs.transferzero.com/docs/payout-details/#brlbank) documentation for the bank_code and transfer_reason lists" 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" PayoutMethodCountryEnum: type: string description: 'The country for the pickup or mobile payout. For USD cash pickup in Nigeria, valid options are: - `NG`: Nigeria For XOF cash pickup, valid options are: - `CI`: Ivory Coast - `ML`: Mali - `SN`: Senegal For XOF mobile payout, valid options are: - `BJ`: Benin - `BF`: Burkina Faso - `CI`: Ivory Coast - `ML`: Mali - `SN`: Senegal - `TG`: Togo For XAF mobile payout, valid options are: - `CG`: Congo - `CM`: Cameroon - `GA`: Gabon - `TD`: Chad' example: SN enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AX - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CY - CZ - DK - DJ - DM - DO - TP - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IL - IT - JM - JP - JO - KZ - KE - KI - KP - KR - KV - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - MS - ME - MA - MZ - MM - NA - NR - NP - NL - AN - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - SH - KN - LC - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SK - SI - SB - SO - ZA - GS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM PayoutMethodDetailsBWPBank: required: - bank_account - bank_name - branch_code - first_name - last_name type: object properties: first_name: type: string last_name: type: string bank_name: type: string bank_account: type: string branch_code: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_name\": \"Banc ABC\",\n \"bank_account\": \"12345678912345678\",\n \"branch_code\": \"550067\",\n}\n```\nSee [BWP Bank](https://docs.transferzero.com/docs/payout-details/#bwpbank) documentation for the bank_name & branch_code list" PayoutMethodDetailsBTC: required: - address - first_name - last_name - name type: object properties: first_name: type: string last_name: type: string name: type: string address: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"name\": \"Full Name\"\n \"address\": \"n4VQ5YdHf7hLQ2gWQYYrcxoE5B7nWuDFNF\"\n}" PayoutMethodDetailsBalance: type: object properties: reference: type: string description: "```JSON\n\"details\": {\n \"reference\": \"Reference\" // optional\n}\n```" PayoutMethodDetailsKESMobile: required: - first_name - identity_card_id - identity_card_type - last_name - mobile_provider - phone_number - street - transfer_reason type: object properties: first_name: type: string last_name: type: string street: type: string city: type: string phone_number: type: string mobile_provider: $ref: '#/components/schemas/PayoutMethodMobileProviderEnum' transfer_reason_code: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' identity_card_type: $ref: '#/components/schemas/PayoutMethodIdentityCardTypeEnum' identity_card_id: type: string relationship_to_sender: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n \"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"street\": \"1 Linford Street\",\n \"city\": \"Nairobi\",\n \"phone_number\": \"+254123456789\", // E.164 international format\n \"identity_card_type\": \"ID\", // refers to the recipient's ID details; Values: \"PP\": Passport, \"ID\": National ID or \"O\": Other\n \"identity_card_id\": 'AB12345678', // refers to the recipient's ID details\n \"transfer_reason\": \"personal_account\",\n \"mobile_provider\": \"mpesa\",\n \"relationship_to_sender\": \"Aunt\" // Optional\n }\n```\n\nSee [KES Mobile](https://docs.transferzero.com/docs/payout-details/#kesmobile) documentation for transfer_reason lists" PayoutMethodDetailsGNFMobile: required: - first_name - last_name - mobile_provider - phone_number type: object properties: first_name: type: string last_name: type: string phone_number: type: string mobile_provider: $ref: '#/components/schemas/PayoutMethodMobileProviderEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+224444044436\", // E.164 international format\n \"mobile_provider\": \"mtn\"\n}\n```" 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 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' 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" FieldSelectValidation: type: object properties: in: type: object description: Describes the valid options for this selectbox readOnly: true example: '20': Current '10': Savings allow_blank: type: boolean description: Describes whether the field is optional or not readOnly: true example: false PayoutMethodDetailsUGXBank: required: - bank_account - branch_code - city - first_name - identity_card_id - last_name - postal_code - street - transfer_reason type: object properties: first_name: type: string last_name: type: string street: type: string city: type: string postal_code: type: string identity_card_id: type: string bank_account: type: string branch_code: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"street\": \"1, Old Taxi Park\",\n \"city\": \"Kampala\",\n \"postal_code\": \"10102\",\n \"identity_card_id\": \"3081900101123411\",\n \"bank_account\": \"1234567890\",\n \"branch_code\": \"130547\",\n \"transfer_reason\": \"personal_account\"\n}\n```\nSee [UGX Bank](https://docs.transferzero.com/docs/payout-details/#ugxbank) documentation for the branch_code list" PayoutMethod: type: object properties: type: type: string description: 'Contains the currency to send the money to, and the type of the money movement Commonly used payout types are: - `NGN::Bank` - for Nigerian bank account payments. - `GHS::Bank` - for Ghanaian bank account payments. - `GHS::Mobile` - for Ghanaian mobile money payments. - `UGX::Mobile` - for Ugandan mobile money payments. - `XOF::Mobile` - for mobile money payments to West-Africa. - `XOF::Bank` - for Senegalese bank account payments. - `XOF::Cash` - for Senegalese cash remittance payments. - `MAD::Cash` - for Moroccan cash remittance payments. - `EUR::Bank` - for IBAN bank transfers in EUR. - `GBP::Bank` - for IBAN bank and FP accounts transfers in GBP. - `ZAR::Bank` - for South Africa bank account payments. - `USD::Bank` - for USD account payments. *** Currently for Egypt, Nigeria and United States only and in Beta phase *** - `USD::Cash` - for USD cash remittance payments. *** Currently for Nigeria only and in Beta phase *** - `KES::Bank` - for Kenyan bank account payments. - `KES::Mobile` - for Kenyan mobile money payments. - `XAF::Mobile` - for mobile money payments to Central African (CEMAC) countries. *** Currently in Beta phase *** - `XAF::Bank` - for Cameroon bank account payments. - `GNF::Mobile` - for mobile money payments to Guinea. - `BRL::Bank` - for Brazilian bank account payments. - `NZD::Bank` - for New Zealand bank account payments. - `BWP::Bank` - for Botswana bank account payments. - `ZMW::Bank` - for Zambian bank account payments. - `CAD::Bank` - for Canadian bank account payments. - `UGX::Bank` - for Ugandan bank account payments. - `EGP::Bank` - for Egyptian bank account payments. - `EGP::Cash` - for Egyptian cash payments. ' example: NGN::Bank details: $ref: '#/components/schemas/PayoutMethodDetails' metadata: type: object description: Metadata of payout method. You can store any kind of information in this field. example: {} id: type: string format: uuid errors: additionalProperties: type: array readOnly: true items: $ref: '#/components/schemas/ValidationErrorDescription' description: The fields that have some problems and don't pass validation readOnly: true example: phone_number: - error: invalid documents: - error: blank fields: type: object additionalProperties: $ref: '#/components/schemas/FieldDescription' description: The fields needed for payments with this payment method with details on validation requirements readOnly: true example: email: type: input validations: inclusion: in: NI: National Id PP: Passport allow_blank: true description: This describes the specific details on how the payment has to be routed to the recipient. example: metadata: {} id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 type: NGN::Bank fields: email: type: input validations: inclusion: in: NI: National Id PP: Passport allow_blank: true errors: phone_number: - error: invalid documents: - error: blank externalDocs: description: Payout Types in the API documentation url: https://docs.transferzero.com/docs/transaction-flow/#payout-type PaginationMeta: type: object properties: pagination: $ref: '#/components/schemas/Pagination' readOnly: true example: pagination: next_page: 3 total_count: 45 total_pages: 5 prev_page: 1 current_page: 2 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 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" 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 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' PayoutMethodBankAccountTypeEnum: type: string description: 'The type of the bank account: - `10`: Savings account - `20`: Current account - `30`: Payment account - `40`: Salary account' example: '10' enum: - '10' - '20' - '30' - '40' PayoutMethodDetailsGHSMobile: required: - first_name - last_name - phone_number type: object properties: first_name: type: string last_name: type: string phone_number: type: string mobile_provider: $ref: '#/components/schemas/PayoutMethodMobileProviderEnum' transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+233302123456\", // E.164 international format\n \"mobile_provider\": \"vodafone\",\n \"transfer_reason\": \"third_party_person_account\"\n}\n```" PayoutMethodDetailsZARBank: required: - bank_account - first_name - last_name - phone_number type: object properties: first_name: type: string last_name: type: string street: type: string postal_code: type: string city: type: string email: type: string bank_code: type: string branch_code: type: string bank_account: type: string phone_number: type: string transfer_reason_code: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' narration: type: string name: type: string contact_first_name: type: string contact_last_name: type: string registration_number: type: string nature_of_business: $ref: '#/components/schemas/PayoutMethodNatureOfBusinessEnum' legal_entity_type: $ref: '#/components/schemas/PayoutMethodLegalEntityTypeEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n \"details\": {\n \"first_name\": \"First\", // Mandatory for personal payouts;\n \"last_name\": \"Last\", // Mandatory for personal payouts;\n \"name\" \"First Ltd\", // Mandatory for business payouts;\n \"contact_first_name\" \"Business\",\n \"contact_last_name\" \"Contact\",\n \"street\": \"Main Street\",\n \"postal_code\": \"AB0001\",\n \"city\": \"Cape Town\",\n \"email\": \"recipient@email.com\",\n \"bank_name\" 'Bank Zero', // Optional\n \"bank_code\": \"334810\", // Optional; Required if branch_code is empty\n \"branch_code\": \"630067\", // Optional; Required if bank_code is empty\n \"bank_account\": \"12345678\",\n \"phone_number\": \"+27119785313\", // E.164 international format\n \"transfer_reason\": \"personal_account\", // New transfer reason field\n \"narration\": \"Birthday Gift\", // Optional\n \"legal_entity_type\": \"sole_proprietorship\", // Optional; Default value is \"person\";\n \"nature_of_business\": \"mining\", // Optional for business payouts;\n \"registration_number\": \"17364BGC\" // Optional for business payouts;\n }\n```\n\nSee [ZAR Bank](https://docs.transferzero.com/docs/payout-details/#zarbank) documentation for the bank_code and transfer_reason lists" PayoutMethodDetailsUSDCash: required: - country - first_name - last_name - phone_number type: object properties: first_name: type: string last_name: type: string phone_number: type: string country: $ref: '#/components/schemas/PayoutMethodCountryEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n \"details\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"phone_number\": \"+2341234567\", // E.164 international format\n \"country\": \"NG\"\n }\n```\nSee [USD Cash](https://docs.transferzero.com/docs/payout-details/#usdcash) documentation for the country list" PayoutMethodPixKeyTypeEnum: type: string description: 'The type of pix key used by the recipient - `cpf`: Natural person register number - `cnpj`: Company registration number - `phone`: Phone number - `email`: Email address - `evp`: Virtual payment address' example: email enum: - cpf - cnpj - phone - email - evp PayoutMethodDetailsNZDBank: required: - bank_account - bank_name - first_name - last_name type: object properties: first_name: type: string last_name: type: string bank_account: type: string bank_name: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_account\": \"1212341234567123\",\n \"bank_name\": \"ASB Bank\"\n}\n```\n\nSee [NZD Bank](https://docs.transferzero.com/docs/payout-details/#nzdbank) documentation for the bank_name list" PayoutMethodDetailsXAFMobile: required: - first_name - last_name - mobile_provider - phone_number type: object properties: first_name: type: string last_name: type: string phone_number: type: string mobile_provider: $ref: '#/components/schemas/PayoutMethodMobileProviderEnum' country: $ref: '#/components/schemas/PayoutMethodCountryEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+237674044436\", // E.164 international format\n \"mobile_provider\": \"orange\",\n \"country\": \"CM\"\n}\n```" PayoutMethodGenderEnum: type: string description: 'The gender of the sender: - `M`: Male - `F`: Female' example: F enum: - M - F PayoutMethodDetailsMobile: required: - first_name - last_name - phone_number type: object properties: first_name: type: string last_name: type: string phone_number: type: string mobile_provider: $ref: '#/components/schemas/PayoutMethodMobileProviderEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+221708766123\" // E.164 international format\n}\n```\n\nPlease note when sending XOF::Cash payments you should subscribe to the recipient.pending webhook, as that will broadcast the payment reference ID the customer need to use to obtain the funds.\nExample webhook response excerpt -\n\n```JSON\n{\n (...)\n \"state\":\"pending\",\n \"metadata\": {\n \"payment_reference\":\"9M5GJRJUBCY\"\n },\n (...)\n}\n```" PayoutMethodDetailsIBAN: required: - first_name - iban - last_name type: object properties: first_name: type: string last_name: type: string iban: type: string bic: type: string bank_name: type: string narration: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"iban\": \"DE89370400440532013000\",\n \"bic\": \"DEUTDEBBXXX\", // Optional\n \"bank_name\": \"Deutsche Bank\", // Optional\n \"narration\": \"Birthday Gift\" // Optional\n}\n```" PayoutMethodCashProviderEnum: type: string description: 'The cash provider for the pickup: For XOF valid options are: - `wizall`: Wizall' example: wizall enum: - wari - wizall PayoutMethodMobileProviderEnum: type: string description: 'The Mobile Wallet provider of the recipient: For XOF (Senegal) valid options are: - `orange`: Orange - `tigo`: Tigo - `emoney`: Emoney - `free`: Free - `expresso` : Expresso - `wave`: Wave For XOF (Ivory Coast) valid options are: - `orange`: Orange - `moov`: Moov - `mtn`: MTN - `wave`: Wave For XOF (Burkina Faso) valid options are: - `orange`: Orange - `mobicash`: Mobicash - `moov` : Moov For XOF (Togo) valid options are: - `moov`: Moov - `tmoney`: Tmoney For XOF (Benin) valid options are: - `moov`: Moov - `mtn`: Mtn For XOF (Mali) valid options are: - `orange`: Orange - `mobicash`: Mobicash - `tigo` : Tigo For GHS valid options are: - `airteltigo`: AirtelTigo - `mtn`: MTN - `vodafone`: Vodafone For KES valid options are: - `mpesa`: MPESA For UGX valid options are: - `africell`: Africell - `airtel`: Airtel - `mtn`: MTN - `telecom`: Telecom For XAF (Chad) valid options are: - `moov`: Moov For XAF (Cameroon) valid options are: - `orange`: Orange - `mtn`: MTN For XAF (Congo) valid options are: - `airtel`: Airtel - `mtn`: MTN For XAF (Gabon) valid options are: - `airtel`: Airtel - `moov`: Moov For GNF (Guinea) valid options are: - `orange`: Orange - `mtn`: MTN' example: orange enum: - africell - airtel - airteltigo - emoney - expresso - free - mobicash - moov - mpesa - mtn - orange - telecom - tigo - tmoney - vodafone - wave PayoutMethodNatureOfBusinessEnum: type: string description: "Nature of business options (used only with a Business sender)\n\nAvailable values:\n - personal: Personal\n - agriculture_and_hunting: Agriculture and Hunting\n - forestry: Forestry\n - fishing: Fishing\n - agricultural_by_products: Agricultural By-Products\n - coal_mining: Coal Mining\n - oil_mining: Oil Mining\n - iron_ore_mining: Iron Ore Mining\n - other_metal_and_diamond_mining: Other Metal and Diamond Mining\n - other_mineral_mining: Other Mineral Mining\n - manufacturing_of_food_drink_tobacco: Manufacture of Food/Drink/Tobacco\n - manufacturing_of_textiles_leather_fur_furniture: Manufacture of Textiles/Leather/Fur/Furniture\n - manufacture_of_wooden_products_furniture: Manufacture of Wooden Products/Furniture\n - manufacture_of_paper_pulp_allied_products: Manufacture of Paper/Pulp/Allied Products\n - manufacture_of_chemicals_medical_petroleum_rubber_plastic_products: Manufacture Of Chemicals Medical Petroleum Rubber Plastic Products\n - manufacture_of_pottery_china_glass_stone: Manufacture Of Pottery China Glass Stone\n - manufacture_of_iron_steel_non_ferrous_metals_basic_industries: Manufacture Of Iron Steel Non-Ferrous Metals Basic Industries\n - manufacture_of_metal_products_electrical_and_scientific_engineering: Manufacture Of Metal Products Electrical And Scientific Engineering\n - manufacture_of_jewelry_musical_instruments_toys: Manufacture Of Jewelry Musical Instruments Toys\n - electricity_gas_and_water: Electricity, Gas And Water\n - construction: Construction\n - wholesale_trade: Wholesale Trade\n - retail_trade: Retail Trade\n - catering_incl_hotels: Catering Incl. Hotels\n - transport_storage: Transport Storage\n - communications: Communications\n - finance_and_holding_companies: Finance And Holding Companies\n - insurance: Insurance\n - business_services: Business Services\n - real_estate_development_investment: Real Estate Development Investment\n - central_state_governments: Central State Governments\n - community_services_defence_police_prisons_etc: Community Services Defence Police Prisons Etc\n - social_services_education_health_care: Social Services Education Health Care\n - personal_services_leisure_services: Personal Services - Leisure Services\n - personal_services_domestic_laundry_repairs: Personal Services - Domestic Laundry Repairs\n - personal_services_embassies_international_organisations: Personal Services - Embassies" example: personal enum: - personal - agriculture_and_hunting - forestry - fishing - agricultural_by_products - coal_mining - oil_mining - iron_ore_mining - other_metal_and_diamond_mining - other_mineral_mining - manufacturing_of_food_drink_tobacco - manufacturing_of_textiles_leather_fur_furniture - manufacture_of_wooden_products_furniture - manufacture_of_paper_pulp_allied_products - manufacture_of_chemicals_medical_petroleum_rubber_plastic_products - manufacture_of_pottery_china_glass_stone - manufacture_of_iron_steel_non_ferrous_metals_basic_industries - manufacture_of_metal_products_electrical_and_scientific_engineering - manufacture_of_jewelry_musical_instruments_toys - electricity_gas_and_water - construction - wholesale_trade - retail_trade - catering_incl_hotels - transport_storage - communications - finance_and_holding_companies - insurance - business_services - real_estate_development_investment - central_state_governments - community_services_defence_police_prisons_etc - social_services_education_health_care - personal_services_leisure_services - personal_services_domestic_laundry_repairs - personal_services_embassies_international_organisations PayoutMethodDetailsKESBank: required: - bank_account - bank_code - first_name - identity_card_id - identity_card_type - last_name - street - transfer_reason type: object properties: first_name: type: string last_name: type: string street: type: string city: type: string bank_code: type: string bank_account: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' identity_card_type: $ref: '#/components/schemas/PayoutMethodIdentityCardTypeEnum' identity_card_id: type: string relationship_to_sender: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n \"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"street\": \"Main Street\",\n \"city\": \"Nairobi\",\n \"bank_code\": \"68\",\n \"bank_account\": \"12345678\",\n \"transfer_reason\": \"personal_account\", // New transfer reason field\n \"identity_card_type\": \"ID\", // refers to the recipient's ID details; Values: \"PP\": Passport, \"ID\": National ID or \"O\": Other\n \"identity_card_id\": \"AB12345678\", // refers to the recipient's ID details\n \"relationship_to_sender\": \"Relative\" // Optional\n }\n```\n\nSee [KES Bank](https://docs.transferzero.com/docs/payout-details/#kesbank) documentation for the `bank_code` and `transfer_reason` lists" PayoutMethodDetailsEGPCash: required: - first_name - last_name - middle_name - phone_number - street - transfer_reason type: object properties: first_name: type: string middle_name: type: string last_name: type: string phone_number: type: string street: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' email: type: string reference: type: string description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"middle_name\": \"Middle\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+201023456789\",\n \"street\": \"1 Main Street\",\n \"transfer_reason\": \"personal_account\",\n \"email\": \"recipient@email.com\", // Optional\n \"reference\": \"3414006608\" // Optional reference that'll appear on the recipient pickup notification (if provided must be unique and exactly 10 digits long)\n}" PayoutMethodDetailsXOFCash: required: - cash_provider - first_name - last_name - phone_number type: object properties: first_name: type: string last_name: type: string phone_number: type: string cash_provider: $ref: '#/components/schemas/PayoutMethodCashProviderEnum' country: $ref: '#/components/schemas/PayoutMethodCountryEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+221774044436\", // E.164 international format\n \"cash_provider\": \"wizall\" // Mandatory; Values: \"wizall\";\n \"country\": \"SN\" // Optional; Values: \"CI\", \"ML\" or \"SN\"; Default value is \"SN\";\n}\n```\n\nPlease note all senders trying to create Wizall cash pickup requests must have `identity_type` and `identity_number` present. The fields above are generally considered optional for senders for other payment corridors. If you wish to use an existing sender who has some of these fields missing you can provide them alongside the `id` or `external_id` field in the sender details.\nFor example -\n\n```JSON\n{\n \"transaction\": {\n \"sender\": {\n \"external_id\": \"\",\n \"identity_type\": \"ID\",\n \"identity_number\": \"AB12345678\",\n (...)\n },\n (...)\n }\n}\n```" PayoutMethodIdentityCardTypeEnum: type: string description: 'The type of the identity card used by the sender or recipient: - `PP`: Passport - `ID`: National Identity Card - `O`: Other type of identity card - `DL`: Driving License - `OT`: Other type of identity card' example: PP enum: - O - PP - ID - DL - OT ValidationErrorDescription: type: object properties: error: type: string description: Describes what the problem is with the field readOnly: true example: invalid description: The description of the error readOnly: true example: error: invalid PayoutMethodDetailsUSDBank: required: - country - first_name - last_name type: object properties: first_name: type: string middle_name: type: string last_name: type: string phone_number: type: string bank_code: type: string bank_account: type: string bank_account_type: $ref: '#/components/schemas/PayoutMethodBankAccountTypeEnum' bank_name: type: string routing_number: type: string swift_code: type: string iban: type: string street: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' country: $ref: '#/components/schemas/PayoutMethodCountryEnum' birth_date: type: string description: Date of birth of recipient format: date description: "Nigeria:\n```JSON\n \"details\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"phone_number\": \"+2341234567\", // E.164 international format\n \"bank_code\": \"057\",\n \"bank_account\": \"1234567890\",\n \"country\": \"NG\"\n }\n```\nSee [USD Bank](https://docs.transferzero.com/docs/payout-details/#usdbank) documentation for the bank_code and country lists\n\nUnited States:\n```JSON\n \"details\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"bank_account\": \"1234567890\",\n \"bank_account_type\": \"20\", // 10 for Savings, 20 for Checking\n \"bank_name\": \"US Bank\",\n \"routing_number\": \"091000022\",\n \"swift_code\": \"USBKUS44IMT\",\n \"country\": \"US\"\n }\nSee [USD Bank](https://docs.transferzero.com/docs/payout-details/#usdbank-1) documentation\n\nEgypt:\n```JSON\n \"details\": {\n \"first_name\": \"Jane\",\n \"middle_name\": \"Jill\", // optional\n \"last_name\": \"Doe\",\n \"street\": \"1 Main Street\",\n \"phone_number\": \"+201023456789\",\n \"iban\": \"EG380019000500000000263180002\",\n \"transfer_reason\": \"personal_account\",\n }\n```\nSee [USD Bank](https://docs.transferzero.com/docs/payout-details/#usdbank-2) documentation" 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 PayoutMethodLegalEntityTypeEnum: type: string description: 'The entity type of the recipient. For ZAR personal payouts valid options are: - `person`: Person For ZAR business payouts valid options are: - `sole_proprietorship`: Sole Proprietorship - `privately_owned_company`: Privately Owned Company (Limited Company) - `publicly_owned_company`: Publicly Owned Company (PLC) - `government_owned_entity`: Government Owned Entity Trusts - `partnership`: Partnership - `go`: GO (Majority Owned Subsidiary of State-Owned Company) - `financial_institution`: Financial Institution' example: person enum: - person - sole_proprietorship - privately_owned_company - publicly_owned_company - government_owned_entity - partnership - go - financial_institution PayoutMethodTransferReasonEnum: type: string description: "Reason of transfer\n\nAvailable values:\n - `personal_account`: Sending money into my own account\n - `donations_and_gifts`: Donations and gifts\n - `third_party_person_account`: Sending money to a friend, family member or any third party person\n - `mortgage_repayments`: Mortgage repayments\n - `business_travel_payments`: Business Travel Payments\n - `personal_travel_payments`: Personal Travel Payments\n - `tuition_fees`: Tuition fees\n - `financial_commission_fees`: Commission and fees for financial services\n - `financial_services_proceeds`: Proceeds for financial services charged for advice provided\n - `individual_property_investments`: Investment into property by a foreign individual\n - `other_investments`: Investment by a foreign individual - other\n - `corporate_property_investments`: Investment into property by a foreign corporate entity\n - `immigrants_capital_payments`: Capital payments by immigrants\n - `legal_services`: Legal services\n - `accounting_services`: Accounting services\n - `consulting_services`: Management consulting services\n - `public_relation_services`: Public relation services\n - `ads_and_market_research_services`: Advertising & market research services\n - `managerial_services`: Managerial services\n - `medical_and_dental_services`: Medical and dental services\n - `educational_services`: Educational services\n - `operational_leasing`: Operational leasing\n - `cultural_and_recreational_services`: Cultural and recreational services\n - `salary_resident_out_country`: Salary paid to South African Resident Temporarily Abroad\n - `salary_non_resident_in_country`: Salary paid to a non-resident employee in South Africa\n - `salary_contract_worker_in_country`: Salary paid to a foreign national contract worker in South Africa\n - `social_security_schemes`: Payments to social security schemes\n - `charities_and_religious_bodies`: Payments to charities and religious bodies\n - `donations_and_aid_to_government`: Donations and aid to Government\n - `donations_and_aid_to_private`: Donations and aid to private sector\n - `pensions`: Pensions\n - `annuities`: Annuities\n - `inheritances`: Inheritances\n - `alimony`: Alimony\n - `tax_income`: Tax - Income tax\n - `tax_vat_refunds`: Tax - VAT refunds\n - `tax_other`: Tax - Other\n - `non_life_insurance_premiums`: Insurance premiums (non life/short term)\n - `life_insurance_premiums`: Insurance premiums (life)\n - `dividends`: Dividends\n - `branch_profits`: Branch profits\n - `commision_or_brokerage`: Commission or brokerage\n - `rental`: Rental\n - `individual_investment_income_from_abroad`: Income earned abroad by a resident on an individual investment\n - `shares_sale`: Sale of shares\n - `bonds_sale`: Sale of bonds\n - `money_market_instruments_sale`: Sale of money market instruments\n - `funds_repatriation_of_foreign_bank_account`: Repatriation of funds out of a foreign bank account\n - `mutual_funds_sale_or_collective_investment`: Sale of mutual funds or collective investment schemes\n - `overseas_property_sale`: Sale of overseas property\n - `sale_and_repatriation_of_other_investment`: Sale and repatriation of other investment\n - `repatriation_south_african_reserve_bank_instruction`: Repatriation on instruction by the South African Reserve Bank\n - `resident_loan_from_non_resident_share_holder`: Loan made to a resident by a non-resident shareholder\n - `resident_loan_from_non_resident_third_party`: Loan made to a resident by a non-resident third party\n - `resident_loan_repayment_from_overseas_living_south_african`: Repayment by a South African living overseas of a loan granted by a resident\n - `study_loan_repayment`: Repayment of a study loan\n - `shareholders_loan_repayment`: Repayment of a shareholders loan\n - `third_party_loan_repayment`: Repayment of a third party loan (excluding shareholders)\n - `trade_finance_loan_repayment`: Repayment of a trade finance loan\n - `research_and_development_proceeds`: Proceeds received for research and development services\n - `research_and_development_funding`: Funding received for research and development\n - `machinary_and_equipment_repairs`: Repairs and maintenance on machinery and equipment\n - `architectural_engineering_technical_services`: Architectural, engineering and other technical services\n - `agrigultural_mining_waste_depollution_services`: Agricultural, mining, waste treatment and depollution services\n - `construction_services`: Proceeds for construction services\n - `telecommunication_services`: Payments for telecommunication services\n - `data_news_agency_fees`: Payments for data, news related and news agency fees\n - `road_passenger_services`: Payments for passenger services - road\n - `rail_passenger_services`: Payments for passenger services - rail\n - `sea_passenger_services`: Payments for passenger services - sea\n - `air_passenger_services`: Payments for passenger services - air\n - `road_freight_services`: Payments for freight services - road\n - `rail_freight_services`: Payments for freight services - rail\n - `sea_freight_services`: Payments for freight services - sea\n - `air_freight_services`: Payments for freight services - air\n - `road_postal_and_courier_services`: Payments for postal and courier services - road\n - `rail_postal_and_courier_services`: Payments for postal and courier services - rail\n - `sea_postal_and_courier_services`: Payments for postal and courier services - sea\n - `air_postal_and_courier_services`: Payments for postal and courier services - air\n - `listed_shares_investment`: Investment in listed shares\n - `non_listed_shares_investment`: Investment in non-listed shares\n - `money_market_instruments_investment`: Investment into money market instruments\n - `listed_bonds_investment`: Investment into listed bonds\n - `non_listed_bonds_investment`: Investment into non-listed bonds\n - `reproduce_distribute_rights_license`: Rights assigned for licences to reproduce and/or distribute\n - `patents_and_investions_rights_license`: Rights assigned for using patents and inventions (licensing)\n - `patterns_and_designs_rights`: Rights assigned for using patterns and designs (including industrial processes)\n - `copyrights_rights`: Rights assigned for using copyrights\n - `franchises_and_trademarks_rights`: Rights assigned for using franchises and trademarks\n - `patents_and_inventions_disposal`: Disposal of patents and inventions\n - `patterns_and_designs_disposal`: Disposal of patterns and designs (including industrial processes)\n - `copyrights_disposal`: Disposal of copyrights\n - `franchises_and_trademarks_disposal`: Disposal of franchises and trademarks\n - `sales_of_manuscripts_sound_recordings_films`: Sales of original manuscripts, sound recordings and films\n - `funds_related_to_recording_productions`: Receipt of funds relating to the production of motion pictures, radio and television programs and musical recordings\n - `software_ownership_rights_sale`: The outright selling of ownership rights of software\n - `computer_services`: Computer-related services including maintenance, repair and consultancy\n - `customised_software_sales`: Commercial sales of customised software and related licenses for use of customers\n - `non_customised_software_on_physical_media_periodic_licence_sale`: Commercial sales of non-customised software on physical media with periodic licence to use\n - `non_customised_software_on_pyisical_media_perpetual_use_sale`: Commercial sales of non-customised software provided on physical media with right to perpetual (ongoing) use\n - `non_customised_software_for_downloading_electronically_made_periodic_licence_sale`: Commercial sales of non-customised software provided for downloading or electronically made available with periodic license\n - `non_customised_software_for_downloading_electronically_made_single_payment_sale`: Commercial sales of non-customised software provided for downloading or electronically made available with single payment\n - `fixed_assets_donations_to_sa_government`: Donations to SA Government for fixed assets\n - `fixed_assets_donations_to_corporate_entities`: Donations to corporate entities - fixed assets\n - `property_disinvestment_by_corporate_entity_resident`: Disinvestment of property by a resident corporate entity\n - `other_business_services`: Proceeds for other business services not included elsewhere\n - `institutional_investor_disinvestment`: Disinvestment by resident institutional investor - Collective Investment Scheme\n - `government_services`: Payment for Government Services\n\n### ZAR Bidvest mandate-bypass-eligible keys\n\nThe following short-form values opt a ZAR Bidvest payout into the SARB FinSurv §B.1 mandate-bypass flow (no signed mandate required) when ALL of these conditions hold:\n\n - the payout is on the ZAR Bidvest corridor (not `access_bank`),\n - the recipient is a natural person (`first_name` populated),\n - the requested currency is ZAR,\n - the output amount is ≤ R50,000.\n\nIf any condition is not met, the transaction falls back to the standard mandate-signing flow. Sending any of these keys is therefore safe even when bypass is not active — the value is recorded against the transfer regardless.\n\n - `own_account`: Sending money into my own account\n - `donations_gifts`: Donations and gifts\n - `family_support`: Sending money to a friend, family member or any third party person\n - `mortgage_repayment`: Mortgage repayments\n - `business_travel`: Business Travel Payments\n - `personal_travel`: Personal Travel Payments\n - `tuition_fees`: Tuition fees (also a general-purpose key)\n - `legal_services`: Legal services (also a general-purpose key)\n - `accounting_services`: Accounting services (also a general-purpose key)\n - `management_consulting`: Management consulting services\n - `advertising_market_research`: Advertising and market research services\n - `cultural_recreational`: Cultural and recreational services\n - `salary_resident_abroad`: Salary — SA resident temporarily abroad\n - `salary_non_resident_in_sa`: Salary — non-resident employee in SA\n - `salary_foreign_contract_in_sa`: Salary — foreign contract worker in SA\n - `pensions`: Pensions (also a general-purpose key)\n - `annuities`: Annuities (also a general-purpose key)\n - `inheritances`: Inheritances (also a general-purpose key)\n - `alimony`: Alimony (also a general-purpose key)\n - `dividends`: Dividends (also a general-purpose key)\n - `commission_brokerage`: Commission or brokerage\n - `rental`: Rental (also a general-purpose key)\n - `investment_income`: Income earned abroad on individual investment\n - `architectural_engineering`: Architectural / engineering / technical services\n - `computer_services`: Computer-related services (also a general-purpose key)" example: personal_account enum: - personal_account - donations_and_gifts - third_party_person_account - mortgage_repayments - business_travel_payments - personal_travel_payments - tuition_fees - financial_commission_fees - financial_services_proceeds - individual_property_investments - other_investments - corporate_property_investments - immigrants_capital_payments - legal_services - accounting_services - consulting_services - public_relation_services - ads_and_market_research_services - managerial_services - medical_and_dental_services - educational_services - operational_leasing - cultural_and_recreational_services - salary_resident_out_country - salary_non_resident_in_country - salary_contract_worker_in_country - social_security_schemes - charities_and_religious_bodies - donations_and_aid_to_government - donations_and_aid_to_private - pensions - annuities - inheritances - alimony - tax_income - tax_vat_refunds - tax_other - non_life_insurance_premiums - life_insurance_premiums - dividends - branch_profits - commision_or_brokerage - rental - individual_investment_income_from_abroad - shares_sale - bonds_sale - money_market_instruments_sale - funds_repatriation_of_foreign_bank_account - mutual_funds_sale_or_collective_investment - overseas_property_sale - sale_and_repatriation_of_other_investment - repatriation_south_african_reserve_bank_instruction - resident_loan_from_non_resident_share_holder - resident_loan_from_non_resident_third_party - resident_loan_repayment_from_overseas_living_south_african - study_loan_repayment - shareholders_loan_repayment - third_party_loan_repayment - trade_finance_loan_repayment - research_and_development_proceeds - research_and_development_funding - machinary_and_equipment_repairs - architectural_engineering_technical_services - agrigultural_mining_waste_depollution_services - construction_services - telecommunication_services - data_news_agency_fees - road_passenger_services - rail_passenger_services - sea_passenger_services - air_passenger_services - road_freight_services - rail_freight_services - sea_freight_services - air_freight_services - road_postal_and_courier_services - rail_postal_and_courier_services - sea_postal_and_courier_services - air_postal_and_courier_services - listed_shares_investment - non_listed_shares_investment - money_market_instruments_investment - listed_bonds_investment - non_listed_bonds_investment - reproduce_distribute_rights_license - patents_and_investions_rights_license - patterns_and_designs_rights - copyrights_rights - franchises_and_trademarks_rights - patents_and_inventions_disposal - patterns_and_designs_disposal - copyrights_disposal - franchises_and_trademarks_disposal - sales_of_manuscripts_sound_recordings_films - funds_related_to_recording_productions - software_ownership_rights_sale - computer_services - customised_software_sales - non_customised_software_on_physical_media_periodic_licence_sale - non_customised_software_on_pyisical_media_perpetual_use_sale - non_customised_software_for_downloading_electronically_made_periodic_licence_sale - non_customised_software_for_downloading_electronically_made_single_payment_sale - fixed_assets_donations_to_sa_government - fixed_assets_donations_to_corporate_entities - property_disinvestment_by_corporate_entity_resident - other_business_services - institutional_investor_disinvestment - government_services - own_account - donations_gifts - family_support - mortgage_repayment - business_travel - personal_travel - management_consulting - advertising_market_research - cultural_recreational - salary_resident_abroad - salary_non_resident_in_sa - salary_foreign_contract_in_sa - commission_brokerage - investment_income - architectural_engineering FieldValidation: type: object properties: presence: type: boolean description: Describes whether the field is mandatory or not readOnly: true example: true inclusion: $ref: '#/components/schemas/FieldSelectValidation' format: type: object description: Contains the regex to use to validate the input field readOnly: true example: with: (?-mix:\A\d+\z) PayoutMethodDetailsGHSBank: required: - bank_account - bank_code - first_name - last_name type: object properties: first_name: type: string last_name: type: string bank_code: type: string bank_account: type: string birth_date: type: string description: Date of birth of recipient format: date transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_code\": \"030100\",\n \"bank_account\": \"123456789\",\n \"transfer_reason\": \"third_party_person_account\"\n}\n```\n\nThe current banks supported and their bank_codes values are:\n\n- Access Bank: 280100\n- Barclays Bank: 030100\n- GCB Bank: 040100\n- Ecobank: 130100\n- First National Bank: 330100\n- Heritage Bank: 370100\n- Prudential Bank: 180100\n- Stanbic Bank: 190100\n- Standard Chartered Bank: 020100\n- United Bank for Africa: 060100\n- Zenith Bank: 120100" PayoutMethodDetailsXOFMobile: required: - first_name - last_name - mobile_provider - phone_number type: object properties: first_name: type: string last_name: type: string phone_number: type: string mobile_provider: $ref: '#/components/schemas/PayoutMethodMobileProviderEnum' country: $ref: '#/components/schemas/PayoutMethodCountryEnum' transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"phone_number\": \"+221708766123\", // E.164 international format\n \"mobile_provider\": \"orange\", // \"orange\", \"tigo\", \"emoney\" or \"free\" for Senegal; \"orange\", \"mtn\" or \"moov\" for Ivory Coast; \"orange\" or \"mobicash\" for Burkina Faso and Mali\n \"country\" // Optional; Values: \"SN\" for Senegal; \"CI\" for Ivory Coast; \"ML\" for Mali; \"BF\" for Burkina Faso; Default value is \"SN\"\n \"transfer_reason\": \"personal_account\" // mandatory for Mali payouts, optional otherwise\n}\n```" PayoutMethodDetailsXOFBank: required: - first_name - iban - last_name type: object properties: first_name: type: string last_name: type: string iban: type: string bank_name: type: string bank_country: type: string bank_code: type: string transfer_reason: $ref: '#/components/schemas/PayoutMethodTransferReasonEnum' birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"iban\": \"BJ0610100100144390000769\", # BBAN format\n \"bank_name\": \"Bank Of Africa Bénin\",\n \"bank_country\": \"BJ\", # ISO country code for Benin\n \"bank_code\": \"BJ061\",\n \"transfer_reason\": \"personal_account\",\n \"narration\": \"Birthday Gift\" // Optional\n}\n```\n\nSee [XOF Bank](https://docs.transferzero.com/docs/payout-details/#xofbank) documentation for the bank_code and transfer_reason lists" securitySchemes: AuthorizationKey: type: apiKey description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields name: Authorization-Key in: header AuthorizationSecret: type: apiKey description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields name: Authorization-Secret in: header AuthorizationNonce: type: apiKey description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields name: Authorization-Nonce in: header AuthorizationSignature: type: apiKey description: Please see the [Authentication guide](https://docs.transferzero.com/docs/authentication) on how to use these fields name: Authorization-Signature in: header externalDocs: description: API documentation and onboarding guide url: https://docs.transferzero.com/