openapi: 3.0.2 info: title: TransferZero Account Debits Recipients 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: Recipients paths: /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 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 - name: amount_from in: query description: 'Minimum amount to filter recipients by amount range. Allows filtering results by the specified `amount` range. When using this filter, the `currency` should also be specified. Example: `/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. Allows filtering results by the specified `amount` range. When using this filter, the `currency` should also be specified. Example: `/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. Example: `/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`. Additionally required when filtering by an amount range Example: `/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. Please 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. Example: `/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. Please 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. Example: `/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. Example: `/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. 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" RecipientStateReasonDetails: anyOf: - $ref: '#/components/schemas/StateReasonDetails' PayoutMethodDetailsNGNBank: required: - bank_account - bank_code - first_name - last_name type: object properties: first_name: type: string last_name: type: string bank_code: type: string bank_account: type: string bank_account_type: $ref: '#/components/schemas/PayoutMethodBankAccountTypeEnum' birth_date: type: string description: Date of birth of recipient format: date street: type: string description: "```JSON\n \"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_code\": \"058\",\n \"bank_account\": \"123456789\",\n \"bank_account_type\": \"10\", # 10 for saving, 20 for current accounts\n \"street\": \"1 Main Street\"\n }\n```\n\nSee [NGN Bank](https://docs.azafinance.com/docs/individual-payments/#ngnbank) documentation for the bank_code" RecipientState: type: string description: 'The state of the recipient. Can be one of the following: * `initial`: We haven''t initiated the payout yet, you can still cancel the transaction * `pending`: Payout has been initiated and we''re waiting from a response from the provider. You can try to cancel it at this point, however it will only get cancelled if we get confirmation from our partner that the payment has failed. * `success`: Payout is done, and the recipient has been paid. * `error`: There was an error from the provider, you can find more details in the `state_reason` attribute. We will usually retry the transaction at a later date. You can either wait, edit the recipient or cancel the transaction. * `refunded`: You asked us to cancel the transaction and we refunded the money. * `manual`: There were too many errors on this transaction, and we stopped retrying. Please edit the recipient, contact us or cancel the transaction. * `stuck`: We didn''t receive a response from the provider in time, and we don''t know whether it has been paid our not. Please contact us for further details. * `overpaid`: The recipient was paid out more than was requested (not applicable for most of the payout providers) * `canceled`: The transaction has been cancelled, and we will refund the money soon * `exception`: Some exception has happened; please contact TransferZero' readOnly: true example: initial enum: - initial - pending - success - error - refunded - manual - stuck - overpaid - canceled - exception PayoutMethodCountryEnum: type: string description: 'The country for the pickup or mobile payout. For USD cash pickup in Nigeria, valid options are: - `NG`: Nigeria For XOF cash pickup, valid options are: - `CI`: Ivory Coast - `ML`: Mali - `SN`: Senegal For XOF mobile payout, valid options are: - `BJ`: Benin - `BF`: Burkina Faso - `CI`: Ivory Coast - `ML`: Mali - `SN`: Senegal - `TG`: Togo For XAF mobile payout, valid options are: - `CG`: Congo - `CM`: Cameroon - `GA`: Gabon - `TD`: Chad' example: SN enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AX - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CY - CZ - DK - DJ - DM - DO - TP - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IL - IT - JM - JP - JO - KZ - KE - KI - KP - KR - KV - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - MS - ME - MA - MZ - MM - NA - NR - NP - NL - AN - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - SH - KN - LC - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SK - SI - SB - SO - ZA - GS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM 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 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" 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}" 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 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```" 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 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 TransactionState: type: string description: 'The state of the transaction, which can be one of the following: * `initial`: Transaction is created, but not yet ready to receive payments (waiting for Sender to be KYC''d and approved). * `approved`: Transaction is created and the sender is approved. Payment can be received * `pending`: There''s an active collection to fund the transaction that needs to clear. * `received`: Transaction has received the correct payin amount and will start processing the payouts. * `mispaid`: Transaction received funds, but not the requested amount. The transaction will be resized, and will start payout based on the received funds. * `manual`: Some of the payments to the recipients have run into issues. Please check the recipient statuses for more information. * `paid`: Transaction has received correct payins and has performed payouts to all recipients. No further steps required * `canceled`: The transaction has been cancelled. Transactions are cancelled automatically after one hour if there was no funds received. Once transactions are funded they can be cancelled by the API user unless the recipients have been paid out. * `refunded`: The transaction has been cancelled after it has been funded, but the funds have been returned now to the sender either partially or fully. * `processing`: Transaction has received a payin, it''s processing. * `exception`: An exception happened during the processing of the transaction. Please contact TransferZero' readOnly: true example: initial enum: - initial - approved - pending - received - mispaid - manual - paid - canceled - refunded - processing - exception Recipient: required: - payout_method - requested_amount - requested_currency type: object properties: requested_amount: type: number description: the amount that should be paid to the recipient. This can be in any currency, usually either the input or the output currency. If the value here is not the output currency we will calculate how much the recipient is going to get using the exchange rates active when the transaction was created. example: 750.0 requested_currency: type: string description: the currency of the amount in 3-character alpha ISO 4217 currency format example: NGN payout_method: $ref: '#/components/schemas/PayoutMethod' metadata: type: object description: Additional metadata that can be added to a recipient. These values will be returned on request example: {} created_at: type: string description: Date and time that the recipient was created. format: date-time readOnly: true editable: type: boolean description: Shows whether the recipient can be edited using the PATCH /v1/recipients/{id} endpoint or not readOnly: true example: true retriable: type: boolean description: Shows whether the transaction made to the recipient can be retried or not readOnly: true example: true input_usd_amount: type: number description: Shows how much this payment is worth in USD readOnly: true example: 10 may_cancel: type: boolean description: 'If true it shows that the payment can be cancelled immediately using the DELETE /v1/recipients/{id} endpoint. If false you can still try to cancel it, however it will only gets cancelled once we have confirmation from our partner that the payment has failed.' readOnly: true example: true state_reason: type: string description: In case the payment is unsuccessful it holds the error message associated with the last unsuccessful payout. readOnly: true state_reason_details: $ref: '#/components/schemas/RecipientStateReasonDetails' state: $ref: '#/components/schemas/RecipientState' transaction_id: type: string description: The ID of the transaction that is related to this recipient readOnly: true example: 97e79719-06e4-4794-aeeb-d2d9415d983a transaction_external_id: type: string description: Optional ID that is supplied by partner linking it to the partner's own Transaction ID. example: 806ec63a-a5a7-43cc-9d75-1ee74fbcc026 transaction_state: $ref: '#/components/schemas/TransactionState' exchange_rate: type: number description: The exchange rate used in this payment readOnly: true example: 1000 fee_fractional: type: number description: The fee for this payment in fractional units (for example cents for USD transactions) readOnly: true example: 100 input_amount: type: number description: The amount that had to be paid in for this payment to proceed readOnly: true example: 10 input_currency: type: string description: The currency this payment was paid in readOnly: true example: USD output_amount: type: number description: The amount that will be paid to the recipient readOnly: true example: 10000 output_currency: type: string description: The currency the payment will be delivered in readOnly: true example: NGN id: type: string format: uuid readOnly: true example: 97e79719-06e4-4794-aeeb-d2d9415d983a type: type: string description: 'Type of recipient to create - either person or business (defaults to person) ' example: person enum: - person - business errors: additionalProperties: type: array readOnly: true items: $ref: '#/components/schemas/ValidationErrorDescription' description: The fields that have some problems and don't pass validation readOnly: true example: phone_number: - error: invalid documents: - error: blank mandate_id: type: string description: 'The ID of the mandate that is related to this recipient. This field is present when a ZAR bank mandate signing is required or has been completed.' format: uuid readOnly: true example: 97e79719-06e4-4794-aeeb-d2d9415d983a description: The recipient describes the amount, the currency and the destination where the money should be sent. example: created_at: '2018-06-07T15:12:12.513Z' editable: true retriable: true input_usd_amount: 1031.31 may_cancel: false metadata: {} state: canceled transaction_id: 7901b86c-07cb-4f68-9e25-db48fc5d96d3 transaction_state: manual payout_method: id: 97e79719-06e4-4794-aeeb-d2d9415d983a type: NGN::Bank details: bank_code: 058 bank_account: '123456789' bank_account_type: '10' last_name: English first_name: Johnny metadata: my: data exchange_rate: 1036911.90353524 fee_fractional: 2723 requested_amount: 1000.0 requested_currency: USD input_amount: 908.0 input_currency: UGX output_amount: 941.51600841 output_currency: NGN externalDocs: description: Recipient documentation url: https://docs.transferzero.com/docs/transaction-flow/#requested-amount-and-currency PayoutMethodDetailsZMWBank: required: - bank_account - branch_code - first_name - last_name type: object properties: first_name: type: string last_name: type: string bank_account: type: string branch_code: type: string birth_date: type: string description: Date of birth of recipient format: date description: "```JSON\n\"details\": {\n \"first_name\": \"First\",\n \"last_name\": \"Last\",\n \"bank_account\": \"1234567890\",\n \"branch_code\": \"ZM210003\",\n}\n```\nSee [ZMW Bank](https://docs.transferzero.com/docs/payout-details/#zmwbank) documentation for the branch_code list" StateReasonDetails: type: object properties: code: type: string description: Status code of transaction readOnly: true example: '311' category: type: string description: Main category of status code, it could be paid, unknown, pickupable, temporary_error, recipient_error, sender_error, sender_action_required readOnly: true example: temporary_error messages: type: array description: Tiered messages readOnly: true example: - Temporary error - Switch Error - Issuer/Switch inoperative items: type: string description: type: string description: Public, human readable, detailed error message readOnly: true example: The central switch is not accepting transactions at the moment. We will retry the transaction readOnly: true example: code: '311' category: temporary_error messages: - Temporary error - Retriable - Switch Error - Issuer/Switch inoperative description: The central switch is not accepting transactions at the moment. We will retry the transaction PayoutMethodDetails: oneOf: - $ref: '#/components/schemas/PayoutMethodDetailsNGNBank' - $ref: '#/components/schemas/PayoutMethodDetailsMobile' - $ref: '#/components/schemas/PayoutMethodDetailsXOFMobile' - $ref: '#/components/schemas/PayoutMethodDetailsXOFBank' - $ref: '#/components/schemas/PayoutMethodDetailsXOFCash' - $ref: '#/components/schemas/PayoutMethodDetailsGHSBank' - $ref: '#/components/schemas/PayoutMethodDetailsGHSMobile' - $ref: '#/components/schemas/PayoutMethodDetailsGBPBank' - $ref: '#/components/schemas/PayoutMethodDetailsIBAN' - $ref: '#/components/schemas/PayoutMethodDetailsMADCash' - $ref: '#/components/schemas/PayoutMethodDetailsBalance' - $ref: '#/components/schemas/PayoutMethodDetailsBTC' - $ref: '#/components/schemas/PayoutMethodDetailsZARBank' - $ref: '#/components/schemas/PayoutMethodDetailsUSDBank' - $ref: '#/components/schemas/PayoutMethodDetailsUSDCash' - $ref: '#/components/schemas/PayoutMethodDetailsKESMobile' - $ref: '#/components/schemas/PayoutMethodDetailsKESBank' - $ref: '#/components/schemas/PayoutMethodDetailsXAFMobile' - $ref: '#/components/schemas/PayoutMethodDetailsXAFBank' - $ref: '#/components/schemas/PayoutMethodDetailsGNFMobile' - $ref: '#/components/schemas/PayoutMethodDetailsBRLBank' - $ref: '#/components/schemas/PayoutMethodDetailsNZDBank' - $ref: '#/components/schemas/PayoutMethodDetailsBWPBank' - $ref: '#/components/schemas/PayoutMethodDetailsZMWBank' - $ref: '#/components/schemas/PayoutMethodDetailsCADBank' - $ref: '#/components/schemas/PayoutMethodDetailsUGXBank' - $ref: '#/components/schemas/PayoutMethodDetailsEGPBank' - $ref: '#/components/schemas/PayoutMethodDetailsEGPCash' 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```" 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 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 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 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 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" 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/