# Bank Account Look Up Resolve your customer's bank account information # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "version": "1.0", "title": "Flutterwave APIs", "description": "APIs for Enterprise Customers", "contact": { "name": "Flutterwave", "email": "hi@flutterwavego.com" } }, "servers": [ { "url": "https://developersandbox-api.flutterwave.com", "description": "Dev server" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/banks/account-resolve": { "post": { "operationId": "bank_account_resolve_post", "tags": [ "Banks" ], "summary": "Bank Account Look Up", "description": "Resolve your customer's bank account information", "parameters": [ { "$ref": "#/components/parameters/trace_id" }, { "$ref": "#/components/parameters/scenario_key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bank_account_currency" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/status" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/bank_account_resolve_response" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/400" } } } }, "401": { "description": "Unauthorised request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403" } } } } } } } }, "webhooks": { "charge.completed": { "post": { "tags": [ "charge.completed" ], "summary": "Send charge completion webhook", "operationId": "charge_completed_webhook", "requestBody": { "required": true, "description": "Notification about a completed charge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/charge_completed_webhook_payload" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully" } } } }, "transfer.disburse": { "post": { "tags": [ "transfer.disburse" ], "summary": "Send disbursed transfer webhook", "operationId": "transfer_disburse_webhook", "requestBody": { "required": true, "description": "Notification about a disbursed transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transfer_disburse_webhook_payload" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully" } } } }, "transfer.reversal": { "post": { "tags": [ "transfer.reversal" ], "summary": "Send transfer reversal webhook", "operationId": "transfer_reversal_webhook", "requestBody": { "required": true, "description": "Notification about a transfer reversal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transfer_reversal_webhook_payload" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully" } } } }, "order.authorization": { "post": { "tags": [ "order.authorization" ], "summary": "Send order authorization webhook", "operationId": "order_authorization_webhook", "requestBody": { "required": true, "description": "Notification about an order authorization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/order_authorization_webhook_payload" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully" } } } }, "refund.completed": { "post": { "tags": [ "refund.completed" ], "summary": "Send refund completion webhook", "operationId": "refund_completed_webhook", "requestBody": { "required": true, "description": "Notification about a completed refund", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund_completed_webhook_payload" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the webhook was received successfully" } } } } }, "components": { "parameters": { "trace_id": { "description": "A unique identifier to track this operation. It must be between 12 and 255 characters in length.", "in": "header", "name": "X-Trace-Id", "schema": { "type": "string", "minLength": 12, "maxLength": 255 }, "example": "acb123e4-f567-4a8b-9c0d-1e2f3a4b5c6d" }, "scenario_key": { "in": "header", "name": "X-Scenario-Key", "schema": { "type": "string", "minimum": 1, "maximum": 1000 }, "description": "An optional scenario key that can be used to simulate specific behaviors or test different scenarios within the API. Providing this header allows you to trigger predefined responses or alter data based on the key's value, which can be useful for testing, development, or demonstrating specific functionalities. The key should be a string of 1 to 1000 characters.", "example": "scenario:auth_redirect" } }, "schemas": { "400": { "description": "Bad Request", "type": "object", "properties": { "status": { "type": "string", "nullable": false, "enum": [ "failed" ] }, "error": { "type": "object", "properties": { "type": { "type": "string", "example": "REQUEST_NOT_VALID" }, "code": { "type": "string", "example": "10400" }, "message": { "type": "string", "nullable": true, "example": "Request is not valid" }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string", "example": "amount" }, "message": { "type": "string", "example": "must not be null" } } } } }, "description": "The request cannot be accepted and is malformed and/or missing required parameters." } } }, "401": { "description": "Unauthorized", "type": "object", "properties": { "status": { "type": "string", "nullable": false, "enum": [ "failed" ] }, "message": { "type": "string", "nullable": true, "description": "Invalid API key provided", "example": "UNAUTHORIZED" }, "error": { "type": "object", "properties": { "type": { "type": "string", "example": "UNAUTHORIZED" }, "code": { "type": "string", "example": "10401" }, "message": { "type": "string", "example": "unauthorized" } } } } }, "403": { "description": "Forbidden", "type": "object", "properties": { "status": { "type": "string", "nullable": false, "enum": [ "failed" ] }, "message": { "type": "string", "description": "API key doesn't have permission to access this resource" }, "error": { "type": "object", "properties": { "type": { "type": "string", "example": "FORBIDDEN" }, "code": { "type": "string", "example": "10403" }, "message": { "type": "string", "example": "Forbidden" } } } } }, "status": { "type": "string", "nullable": false, "enum": [ "success", "failed" ] }, "customer_id": { "type": "string", "description": "ID of the customer.", "example": "cus_3XarBILKQS" }, "address": { "type": "object", "description": "Customer address information.", "required": [ "line1", "city", "state", "country", "postal_code" ], "properties": { "city": { "type": "string", "description": "The name of the city.", "example": "New York", "pattern": "^.+$", "x-pattern-message": "value must not be empty" }, "country": { "description": "ISO2 country code", "type": "string", "pattern": "^[A-Z]{2}$", "example": "US", "x-pattern-message": "must be a valid country ISO2 format" }, "line1": { "type": "string", "description": "The first line of the Customer's address.", "example": "123 Main Street", "pattern": "^.+$", "x-pattern-message": "value must not be empty" }, "line2": { "type": "string", "description": "The second line of the Customer's address.", "example": "Apt 4B", "pattern": "^.+$", "x-pattern-message": "value must not be empty" }, "postal_code": { "type": "string", "example": "10001", "pattern": "^.+$", "x-pattern-message": "value must not be empty" }, "state": { "type": "string", "description": "The state or region.", "example": "New York", "pattern": "^.+$", "x-pattern-message": "value must not be empty" } } }, "email": { "type": "string", "description": "The Customer's email address.", "pattern": "^[a-zA-Z0-9_+&*-]+(?:\\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}$", "example": "cornelius@gmail.com", "x-pattern-message": "must be an email format" }, "name": { "type": "object", "description": "The Customer's full name.", "properties": { "first": { "type": "string", "description": "The Customer's first name.", "example": "King", "pattern": "^(?![ ,.'-]*$)[A-Za-z ,.'-]{2,50}$", "x-pattern-message": "must be between 2 and 50 characters long, cannot be empty, only spaces, or only symbols, and can only contain letters, spaces, commas, periods, apostrophes, or hyphens." }, "middle": { "type": "string", "description": "The Customer's middle name.", "example": "Leo", "pattern": "^(?![ ,.'-]*$)[A-Za-z ,.'-]{2,50}$", "x-pattern-message": "must be between 2 and 50 characters long, cannot be empty, only spaces, or only symbols, and can only contain letters, spaces, commas, periods, apostrophes, or hyphens." }, "last": { "type": "string", "description": "The Customer's last name.", "example": "LeBron", "pattern": "^(?![ ,.'-]*$)[A-Za-z ,.'-]{2,50}$", "x-pattern-message": "must be between 2 and 50 characters long, cannot be empty, only spaces, or only symbols, and can only contain letters, spaces, commas, periods, apostrophes, or hyphens." } } }, "phone": { "type": "object", "description": "The customer's mobile number.", "required": [ "number", "country_code" ], "example": { "country_code": "234", "number": "08012345678" }, "properties": { "country_code": { "description": "The dialling country code e.g. 234 for NG.", "type": "string", "pattern": "^[0-9]{1,3}$", "example": "234", "x-pattern-message": "must be a valid 3 digit country code" }, "number": { "description": "Unformatted 7-10-digit phone number without the country code.", "type": "string", "pattern": "^[0-9]{7,10}$", "example": "8001122334", "x-pattern-message": "must be a valid 7 to 10 digit phone number" } } }, "meta": { "type": "object", "additionalProperties": { "type": "string" } }, "customer": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/customer_id" }, "address": { "$ref": "#/components/schemas/address" }, "email": { "$ref": "#/components/schemas/email" }, "name": { "$ref": "#/components/schemas/name" }, "phone": { "$ref": "#/components/schemas/phone" }, "meta": { "$ref": "#/components/schemas/meta" }, "created_datetime": { "type": "string", "format": "date-time" } } }, "amount": { "type": "number", "format": "decimal", "description": "The payment amount in decimals.", "example": 12.34, "minimum": 0.01 }, "currency": { "description": "ISO 4217 currency code.", "type": "string", "example": "NGN", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "AQD", "ARS", "AUD", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BWP", "BYR", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CYP", "CZK", "DJF", "DKK", "DOP", "DZD", "ECS", "EEK", "EGP", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MTL", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SKK", "SLL", "SOS", "SRD", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VEF", "VND", "VUV", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMK", "ZWD", "ZMW", "USDC", "USDT", "RLUSD" ] }, "payment_method_id": { "type": "string", "description": "ID of the payment method.", "example": "pmd_WRq7L4TM8p" }, "base_payment_method": { "required": [ "id", "type" ], "properties": { "id": { "$ref": "#/components/schemas/payment_method_id" }, "type": { "type": "string", "description": "The type of the payment method.", "example": "card" }, "customer_id": { "description": "ID of the customer.", "type": "string", "example": "cus_3XarBILKQS" }, "meta": { "$ref": "#/components/schemas/meta" }, "device_fingerprint": { "description": "The customer's device fingerprint.", "type": "string", "example": "62wd23423rq324323qew1" }, "client_ip": { "description": "The customer's device IP.", "type": "string", "example": "154.123.220.1" }, "created_datetime": { "type": "string", "format": "date-time", "description": "The date and time when the virtual account was created.", "example": "2024-12-03T13:54:21.546559974Z" } } }, "card_network": { "type": "string", "description": "The card network.", "example": "MASTERCARD", "enum": [ "MASTERCARD", "VISA", "AMERICAN EXPRESS", "DISCOVER", "VERVE", "AFRIGO", "UNKNOWN" ] }, "credential_on_file": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Indicates whether the recurring card charge with Credential-on-File (COF) is enabled.", "example": true }, "agreement_id": { "type": "string", "description": "A unique reference generated by Flutterwave during the initial Customer Initiated Transaction (CIT).", "example": "Agreement00w02W1" }, "recurring_amount_variability": { "type": "string", "description": "This indicates whether the amount charged for subsequent payments remains the same, or differs.", "example": "VARIABLE", "enum": [ "VARIABLE" ] }, "agreement_type": { "type": "string", "definition": "This indicates the type of charge agreement with Flutterwave.", "example": "UNSCHEDULED", "enum": [ "UNSCHEDULED" ] }, "trace_id": { "type": "string", "description": "A reference generated by the card scheme during the initial Customer Initiated Transaction (CIT).", "example": "123456789" } } }, "card": { "type": "object", "required": [ "expiry_month", "expiry_year", "first6", "last4", "network" ], "properties": { "expiry_month": { "type": "integer", "description": "Expiry month of the card.", "example": "09" }, "expiry_year": { "type": "integer", "description": "Expiry year of the card.", "example": "32" }, "first6": { "type": "string", "description": "Bank identification number (BIN) of the card.", "minLength": 6, "maxLength": 6, "example": "123412" }, "last4": { "type": "string", "description": "The last four digits of the card number.", "minLength": 4, "maxLength": 4, "example": "1234" }, "network": { "$ref": "#/components/schemas/card_network" }, "billing_address": { "$ref": "#/components/schemas/address" }, "cof": { "$ref": "#/components/schemas/credential_on_file" }, "card_holder_name": { "type": "string", "description": "Name on the card", "example": "Alex James" } } }, "card_payment_method": { "allOf": [ { "$ref": "#/components/schemas/base_payment_method" } ], "type": "object", "required": [ "type", "card" ], "properties": { "type": { "type": "string", "description": "The type of the payment method.", "default": "card", "readOnly": true }, "card": { "$ref": "#/components/schemas/card" } } }, "bank_account": { "type": "object" }, "bank_account_payment_method": { "allOf": [ { "$ref": "#/components/schemas/base_payment_method" } ], "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of the payment method.", "default": "bank_account", "readOnly": true }, "bank_account": { "$ref": "#/components/schemas/bank_account" } } }, "mobile_money": { "type": "object", "required": [ "network", "phone_number", "country_code" ], "properties": { "network": { "type": "string", "description": "The mobile network of the customer's phone number.", "example": "MTN" }, "country_code": { "type": "string", "description": "The dialling country code e.g. 233 for GH.", "example": "233" }, "phone_number": { "type": "string", "description": "The phone number of customer.", "example": "9012345678" }, "qr_code": { "type": "string" } } }, "mobile_money_payment_method": { "allOf": [ { "$ref": "#/components/schemas/base_payment_method" } ], "type": "object", "required": [ "type", "mobile_money" ], "properties": { "type": { "type": "string", "description": "The type of the payment method.", "default": "mobile_money", "readOnly": true }, "mobile_money": { "$ref": "#/components/schemas/mobile_money" } } }, "opay": { "type": "object" }, "opay_payment_method": { "allOf": [ { "$ref": "#/components/schemas/base_payment_method" } ], "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of the payment method.", "default": "opay", "readOnly": true }, "opay": { "$ref": "#/components/schemas/opay" } } }, "applepay": { "type": "object", "properties": { "card_holder_name": { "type": "string", "description": "The cardholder name.", "example": "Yohan Blake" } } }, "applepay_payment_method": { "allOf": [ { "$ref": "#/components/schemas/base_payment_method" } ], "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of the payment method.", "default": "applepay", "readOnly": true }, "applepay": { "$ref": "#/components/schemas/applepay" } } }, "googlepay": { "type": "object", "properties": { "card_holder_name": { "type": "string", "description": "The cardholder name.", "example": "Yohan Blake" } } }, "googlepay_payment_method": { "allOf": [ { "$ref": "#/components/schemas/base_payment_method" } ], "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of the payment method.", "default": "googlepay", "readOnly": true }, "googlepay": { "$ref": "#/components/schemas/googlepay" } } }, "ussd": { "type": "object", "properties": { "account_bank": { "type": "string", "description": "The bank code of the USSD string to generate.", "example": "050" } } }, "ussd_payment_method": { "allOf": [ { "$ref": "#/components/schemas/base_payment_method" } ], "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of the payment method.", "default": "ussd", "readOnly": true }, "ussd": { "$ref": "#/components/schemas/ussd" } } }, "pwbt_type": { "type": "string", "description": "The type of virtual account.", "example": "static", "enum": [ "static", "dynamic" ] }, "pwbt": { "type": "object", "required": [ "account_type" ], "properties": { "account_expires_in": { "type": "integer", "description": "The expiry time of the virtual account.", "example": 360, "maximum": 432000 }, "account_display_name": { "type": "string", "description": "The name that is shown to the customer when the account is resolved to a name.", "example": "Alex James", "minLength": 3, "maxLength": 256 }, "account_type": { "$ref": "#/components/schemas/pwbt_type" }, "originator_bank_name": { "type": "string", "description": "The sender's Bank name", "example": "Mock Bank" }, "originator_account_number": { "type": "string", "description": "The Sender's masked account number", "example": "002*******78" }, "originator_name": { "type": "string", "description": "The sender's name", "example": "Jane Doe" } } }, "pwbt_payment_method": { "allOf": [ { "$ref": "#/components/schemas/base_payment_method" } ], "type": "object", "required": [ "type", "bank_transfer" ], "properties": { "type": { "type": "string", "description": "The type of the payment method.", "default": "bank_transfer", "readOnly": true }, "bank_transfer": { "$ref": "#/components/schemas/pwbt" } } }, "payment_method": { "oneOf": [ { "$ref": "#/components/schemas/card_payment_method" }, { "$ref": "#/components/schemas/bank_account_payment_method" }, { "$ref": "#/components/schemas/mobile_money_payment_method" }, { "$ref": "#/components/schemas/opay_payment_method" }, { "$ref": "#/components/schemas/applepay_payment_method" }, { "$ref": "#/components/schemas/googlepay_payment_method" }, { "$ref": "#/components/schemas/ussd_payment_method" }, { "$ref": "#/components/schemas/pwbt_payment_method" } ], "discriminator": { "propertyName": "type", "mapping": { "card": "#/components/schemas/card_payment_method", "bank_account": "#/components/schemas/bank_account_payment_method", "mobile_money": "#/components/schemas/mobile_money_payment_method", "opay": "#/components/schemas/opay_payment_method", "applepay": "#/components/schemas/applepay_payment_method", "googlepay": "#/components/schemas/googlepay_payment_method", "ussd": "#/components/schemas/ussd_payment_method", "bank_transfer": "#/components/schemas/pwbt_payment_method" } } }, "reference": { "type": "string", "pattern": "^[a-zA-Z0-9\\-]+$", "minLength": 6, "maxLength": 42, "description": "A custom identifier to track the transaction, This must be unique across all your transactions.", "x-pattern-message": "must be an alphanumeric string" }, "processor_response": { "type": "object", "required": [ "type", "code" ], "properties": { "type": { "type": "string" }, "code": { "type": "string", "pattern": "\\d{2}", "x-pattern-message": "must be two digits" } }, "enum": [ { "type": "approved", "code": "00" }, { "type": "refer_to_issuer", "code": "01" }, { "type": "refer_to_issuer_special_condition", "code": "02" }, { "type": "invalid_merchant", "code": "03" }, { "type": "pick_up_card_no_fraud", "code": "04" }, { "type": "do_not_honor", "code": "05" }, { "type": "error", "code": "06" }, { "type": "pick_up_card_fraud", "code": "07" }, { "type": "partial_approval", "code": "10" }, { "type": "invalid_transaction", "code": "12" }, { "type": "invalid_amount", "code": "13" }, { "type": "invalid_account_number", "code": "14" }, { "type": "no_such_issuer", "code": "15" }, { "type": "reenter_transaction", "code": "19" }, { "type": "no_action_taken", "code": "21" }, { "type": "unable_to_locate_record_in_file", "code": "25" }, { "type": "file_temporarily_not_available", "code": "28" }, { "type": "lost_card_pick_up", "code": "41" }, { "type": "stolen_card_pick_up", "code": "43" }, { "type": "insufficient_funds", "code": "51" }, { "type": "no_checking_account", "code": "52" }, { "type": "no_savings_account", "code": "53" }, { "type": "expired_card", "code": "54" }, { "type": "incorrect_pin", "code": "55" }, { "type": "transaction_not_permitted_card", "code": "57" }, { "type": "transaction_not_permitted_terminal", "code": "58" }, { "type": "suspected_fraud", "code": "59" }, { "type": "exceeds_approval_amount_limit", "code": "61" }, { "type": "invalid_restricted_service_code", "code": "62" }, { "type": "security_violation", "code": "63" }, { "type": "transaction_does_not_fulfill_aml_req", "code": "64" }, { "type": "exceeds_withdrawal_limit", "code": "65" }, { "type": "pin_data_required", "code": "70" }, { "type": "pin_entry_tries_exceeded", "code": "75" }, { "type": "unsolicited_reversal", "code": "76" }, { "type": "blocked_first_use", "code": "78" }, { "type": "already_reversed", "code": "79" }, { "type": "negative_cvv_result", "code": "82" }, { "type": "no_reason_to_decline", "code": "85" }, { "type": "cannot_verify_pin", "code": "86" }, { "type": "issuer_unavailable", "code": "91" }, { "type": "unable_to_route_transaction", "code": "92" }, { "type": "cannot_complete_violation_of_law", "code": "93" }, { "type": "system_error", "code": "96" }, { "type": "invalid_cvv", "code": "97" } ] }, "bank_account_resolve": { "type": "object", "properties": { "code": { "type": "string", "description": "The bank or institution code.", "example": "044", "minLength": 2, "maxLength": 10 }, "number": { "type": "string", "description": "The bank account number.", "example": "0690000031", "minLength": 4, "maxLength": 50 } }, "required": [ "code", "number" ] }, "ngn_bank_account_resolve": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code.", "default": "NGN", "example": "NGN", "readOnly": true }, "account": { "allOf": [ { "$ref": "#/components/schemas/bank_account_resolve" }, { "type": "object", "properties": { "code": { "type": "string", "description": "The bank code.", "example": "044", "pattern": "^\\d+$", "minLength": 3, "maxLength": 10 }, "number": { "type": "string", "description": "The bank account number.", "example": "0690000040", "minLength": 10, "maxLength": 10, "pattern": "^\\d+$" } } } ] } }, "required": [ "currency", "account" ] }, "gbp_bank_individual": { "allOf": [ { "$ref": "#/components/schemas/bank_account_resolve" }, { "type": "object", "properties": { "type": { "type": "string", "description": "The bank account type.", "default": "personal", "readOnly": true }, "name": { "allOf": [ { "$ref": "#/components/schemas/name" }, { "type": "object", "required": [ "first", "last" ] } ] } }, "required": [ "type", "name" ] } ] }, "gbp_bank_corporate": { "allOf": [ { "$ref": "#/components/schemas/bank_account_resolve" }, { "type": "object", "properties": { "type": { "type": "string", "description": "The bank account type.", "default": "corporate", "example": "corporate", "readOnly": true }, "business_name": { "type": "string", "description": "The business name attached to the bank account.", "example": "Ajadi & Sons Ltd.", "minLength": 2, "maxLength": 50 } }, "required": [ "type", "business_name" ] } ] }, "gbp_bank_account_type": { "oneOf": [ { "$ref": "#/components/schemas/gbp_bank_individual" }, { "$ref": "#/components/schemas/gbp_bank_corporate" } ], "discriminator": { "propertyName": "type", "mapping": { "individual": "#/components/schemas/gbp_bank_individual", "corporate": "#/components/schemas/gbp_bank_corporate" } } }, "gbp_bank_account_resolve": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code.", "default": "GBP", "example": "GBP", "readOnly": true }, "account": { "$ref": "#/components/schemas/gbp_bank_account_type" } }, "required": [ "currency", "account" ] }, "usd_bank_ng": { "allOf": [ { "$ref": "#/components/schemas/bank_account_resolve" }, { "type": "object", "properties": { "country": { "type": "string", "default": "NG", "readOnly": true } }, "required": [ "country" ] } ] }, "usd_bank_country": { "oneOf": [ { "$ref": "#/components/schemas/usd_bank_ng" } ], "discriminator": { "propertyName": "country", "mapping": { "NG": "#/components/schemas/usd_bank_ng" } } }, "usd_bank_account_resolve": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code.", "default": "USD", "example": "USD", "readOnly": true }, "account": { "$ref": "#/components/schemas/usd_bank_country" } }, "required": [ "currency", "account" ] }, "bank_account_currency": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ngn_bank_account_resolve" }, { "$ref": "#/components/schemas/gbp_bank_account_resolve" }, { "$ref": "#/components/schemas/usd_bank_account_resolve" } ], "discriminator": { "propertyName": "currency", "mapping": { "NGN": "#/components/schemas/ngn_bank_account_resolve", "GBP": "#/components/schemas/gbp_bank_account_resolve", "USD": "#/components/schemas/usd_bank_account_resolve" } } }, "bank_account_resolve_response": { "type": "object", "properties": { "bank_code": { "type": "string", "description": "The bank code.", "example": "044" }, "account_number": { "type": "string", "description": "The bank account number.", "example": "0690000040" }, "account_name": { "type": "string", "description": "The bank account name.", "example": "Alex James" } } }, "provider_response": { "type": "object", "required": [ "type", "code" ], "description": "Represents payout error codes. The `type` and `code` fields are separate enums where:\n- `type` indicates the nature of the error.\n- `code` provides the specific error code associated with the error type.\n- `message` explains the meaning of the `type-code` pair\n", "properties": { "message": { "type": "string", "description": "The processor message for the transfer.", "example": "DISBURSE FAILED: Insufficient wallet balance" }, "type": { "type": "string", "description": "The type of the payout error, representing the specific error scenario.\n", "enum": [ "transfer_amount_exceeds_limit", "transfer_amount_below_limit", "monthly_transfer_limit_exceeded", "daily_transfer_limit_exceeded", "transfer_limit_not_set_for_currency", "payout_creation_failed", "insufficient_balance", "service_unavailable", "transfer_failed", "pricing_not_set", "currency_conversion_not_set", "rejected_recipient_merchant", "invalid_bank_code", "unable_to_determine_country", "invalid_wallet_currency" ] }, "code": { "type": "string", "description": "The unique code associated with the error type. This code follows a pattern of four digits.\n", "pattern": "\\d{4}" } } }, "refund": { "description": "A refund of a previously created charge", "type": "object", "properties": { "id": { "description": "ID of the refund", "type": "string" }, "amount_refunded": { "allOf": [ { "$ref": "#/components/schemas/amount" } ], "description": "Amount of the refund" }, "meta": { "$ref": "#/components/schemas/meta" }, "reason": { "type": "string", "enum": [ "duplicate", "fraudulent", "requested_by_customer", "expired_uncaptured_charge" ], "description": "Reason for the refund", "example": "requested_by_customer" }, "status": { "type": "string", "enum": [ "pending", "requires_action", "succeeded", "failed", "cancelled", "completed", "new" ], "description": "Status of the refund", "example": "new" }, "charge_id": { "type": "string", "description": "ID of the charge tied to this refund", "example": "chg_VnUihmASmF" }, "created_datetime": { "type": "string" } } }, "base_webhook_payload": { "type": "object", "description": "Base webhook payload schema", "required": [ "data", "type", "timestamp", "webhook_id" ], "properties": { "webhook_id": { "type": "string", "description": "Webhook event identifier" }, "timestamp": { "type": "integer", "format": "int64", "description": "Webhook event timestamp" }, "type": { "type": "string", "description": "Webhook event type", "enum": [ "charge.completed", "transfer.disburse", "transfer.reversal", "order.authorization" ] }, "data": { "type": "object" } } }, "charge_completed_webhook_payload": { "type": "object", "description": "Charge completion webhook payload", "allOf": [ { "$ref": "#/components/schemas/base_webhook_payload" }, { "type": "object", "properties": { "type": { "type": "string", "readOnly": true, "default": "charge.completed" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the charge" }, "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" }, "customer": { "$ref": "#/components/schemas/customer" }, "description": { "type": "string", "description": "Description of the charge." }, "meta": { "$ref": "#/components/schemas/meta" }, "payment_method": { "$ref": "#/components/schemas/payment_method" }, "redirect_url": { "type": "string", "description": "Specifies the URL to redirect to." }, "reference": { "$ref": "#/components/schemas/reference" }, "status": { "type": "string", "description": "The status of the charge" }, "processor_response": { "$ref": "#/components/schemas/processor_response" }, "created_datetime": { "type": "string", "format": "date-time" } } } } } ] }, "base_transfer_webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the transfer" }, "type": { "type": "string", "default": "bank", "readOnly": true }, "source_currency": { "allOf": [ { "$ref": "#/components/schemas/currency" } ], "description": "The currency in which the transfer was debited.", "example": "NGN" }, "destination_currency": { "allOf": [ { "$ref": "#/components/schemas/currency" } ], "description": "The currency in which the amount will be credited to the recipient.", "example": "EUR" }, "amount": { "description": "Amount to be sent to the recipient. This is a positive integer in the smallest currency unit", "type": "integer", "format": "decimal", "minimum": 1, "example": 3000.44 }, "reference": { "$ref": "#/components/schemas/reference" }, "proof": { "type": "string", "description": "Transfer proof" }, "status": { "description": "The status of the transfer.", "type": "string", "enum": [ "FAILED", "SUCCESSFUL" ] }, "disburse_datetime": { "type": "string", "format": "date-time" }, "bank": { "type": "object", "properties": { "account_number": { "description": "recipient account number", "type": "string", "example": "0690000031", "minLength": 10 }, "code": { "description": "recipient bank code", "type": "string", "example": "044", "minLength": 2, "maxLength": 10 }, "branch": { "description": "recipient bank branch", "type": "string", "example": "1812051EPC", "minLength": 2 }, "name": { "description": "recipient bank name", "type": "string", "example": "Commonwealth Bank of Australia" }, "routing_number": { "description": "recipient bank routing number", "type": "string", "example": "110000", "minLength": 2 }, "swift_code": { "description": "recipient bank swift code", "type": "string", "example": "CTBAAU2S", "minLength": 2 } } }, "mobile_money": { "type": "object", "properties": { "network": { "description": "recipient network", "type": "string" }, "country": { "description": "recipient country", "type": "string", "minLength": 2, "maxLength": 25, "pattern": "^[a-zA-Z0-9]*$", "example": "MTN" }, "msisdn": { "description": "recipient phone number", "type": "string", "minLength": 6, "maxLength": 25, "pattern": "^[a-zA-Z0-9]*$", "example": "251911234567" } } }, "wallet": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "flutterwave" ], "description": "Specifies the payment or service provider. Currently, only \"flutterwave\" is supported" }, "identifier": { "description": "A unique identifier assigned to the merchant by the payment or service provider.", "type": "string", "example": "00118468", "minLength": 7, "maxLength": 25, "pattern": "^[a-zA-Z0-9]*$" } } }, "cash_pickup": { "type": "object", "properties": { "network": { "description": "cashpickup network", "type": "string" } } }, "fee": { "type": "object", "properties": { "currency": { "allOf": [ { "$ref": "#/components/schemas/currency" } ], "description": "The currency in which the fee is charged." }, "value": { "type": "number", "description": "The amount charged as a fee for the transfer.", "format": "double", "minimum": 0, "example": 10.35 } } }, "debit_information": { "type": "object", "properties": { "currency": { "allOf": [ { "$ref": "#/components/schemas/currency" } ], "description": "The currency in which the fees and charges are applied for the transfer." }, "actual_debit_amount": { "type": "number", "description": "The exact amount deducted for the transfer, including applicable fees.", "format": "decimal", "minimum": 0, "example": 100.35 }, "rate_used": { "type": "number", "description": "The exchange rate applied to calculate the transfer amount.", "format": "decimal", "minimum": 0, "example": 100.35 }, "vat": { "type": "number", "description": "The Value-Added Tax (VAT) amount charged for the transfer.", "format": "decimal", "minimum": 0, "example": 100.35 } } }, "payment_information": { "type": "object", "properties": { "proof": { "type": "string", "description": "Session ID", "example": "11000224070317345400001414441712312381" } } }, "provider_response": { "$ref": "#/components/schemas/provider_response" }, "meta": { "$ref": "#/components/schemas/meta" } } }, "transfer_disburse_webhook_payload": { "type": "object", "description": "Disbursed Transfer webhook payload", "allOf": [ { "$ref": "#/components/schemas/base_webhook_payload" }, { "type": "object", "properties": { "type": { "type": "string", "readOnly": true, "default": "transfer.disburse" }, "data": { "allOf": [ { "$ref": "#/components/schemas/base_transfer_webhook" } ] } } } ] }, "transfer_reversal_webhook_payload": { "type": "object", "description": "Transfer Reversal webhook payload", "allOf": [ { "$ref": "#/components/schemas/base_webhook_payload" }, { "type": "object", "properties": { "type": { "type": "string", "readOnly": true, "default": "transfer.reversal" }, "data": { "allOf": [ { "$ref": "#/components/schemas/base_transfer_webhook" }, { "type": "object", "properties": { "reversal": { "type": "object", "properties": { "reversal_datetime": { "type": "string", "format": "date-time" }, "initial_status": { "type": "string", "example": "SUCCESSFUL" }, "reconciliation_status": { "type": "string", "example": "REVERSED" }, "reconciliation_type": { "type": "string", "enum": [ "D", "C" ] } } } } } ] } } } ] }, "order_authorization_webhook_payload": { "type": "object", "description": "Order authorization webhook payload", "allOf": [ { "$ref": "#/components/schemas/base_webhook_payload" }, { "type": "object", "properties": { "type": { "type": "string", "readOnly": true, "default": "order.authorization" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the order" }, "amount": { "$ref": "#/components/schemas/amount" }, "currency": { "$ref": "#/components/schemas/currency" }, "customer": { "$ref": "#/components/schemas/customer" }, "description": { "type": "string", "description": "Description of the order." }, "meta": { "$ref": "#/components/schemas/meta" }, "payment_method": { "$ref": "#/components/schemas/payment_method" }, "redirect_url": { "type": "string", "description": "Specifies the URL to redirect to." }, "reference": { "$ref": "#/components/schemas/reference" }, "status": { "type": "string", "description": "The status of the order" }, "processor_response": { "$ref": "#/components/schemas/processor_response" }, "created_datetime": { "type": "string", "format": "date-time" } } } } } ] }, "refund_completed_webhook_payload": { "type": "object", "description": "Refund completion webhook payload", "allOf": [ { "$ref": "#/components/schemas/base_webhook_payload" }, { "type": "object", "properties": { "type": { "type": "string", "readOnly": true, "default": "refund.completed" }, "data": { "$ref": "#/components/schemas/refund" } } } ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "_id": { "buffer": { "0": 102, "1": 126, "2": 178, "3": 152, "4": 33, "5": 232, "6": 98, "7": 0, "8": 59, "9": 50, "10": 178, "11": 253 } } } ```