### Callback URL Response Example

Source: https://developer.flutterwave.com/docs/general-transfer-flow

This is an example of a response received at the `callback_url` provided during transfer creation. It contains details about the transfer's completion or failure.

```APIDOC
## Callback URL Response

This is an example of a response received at the `callback_url` provided during transfer creation. It contains details about the transfer's completion or failure.

```json
{
  "webhook_id": "wbk_rp0bjKyAWA52ViM8xlZ0",
  "timestamp": 1739877172874,
  "type": "transfer.disburse",
  "data": {
    "id": "trf_yMZATJ11yVPNkZ",
    "type": "BANK",
    "source_currency": "NGN",
    "destination_currency": "NGN",
    "amount": 50000,
    "reference": "5748745ug8ufdgjhveyebjhcdbchb",
    "status": "SUCCESSFUL",
    "bank": {
      "account_number": "0122333334",
      "code": "044",
      "branch": null,
      "name": null,
      "routing_number": null,
      "swift_code": null
    },
    "fee": {
      "currency": "NGN",
      "value": 500
    },
    "debit_information": {
      "currency": "NGN",
      "actual_debit_amount": 50000,
      "rate_used": 0.00123,
      "vat": 3750
    },
    "payment_information": {
      "proof": "504828363550713897092362940989"
    },
    "meta": {}
  }
}
```
```

--------------------------------

### Callback URL Response Example

Source: https://developer.flutterwave.com/docs/direct-transfer-flow

This is an example of the JSON response sent to the provided `callback_url` when a transfer is completed or fails. It contains details about the transfer status.

```APIDOC
## Callback URL Response

### Description
This is an example of the JSON response sent to the provided `callback_url` when a transfer is completed or fails. It contains details about the transfer status.

### Response Body
```json
{
  "webhook_id": "wbk_rp0bjKyAWA52ViM8xlZ0",
  "timestamp": 1739877172874,
  "type": "transfer.disburse",
  "data": {
    "id": "trf_yMZATJ11yVPNkZ",
    "type": "BANK",
    "source_currency": "NGN",
    "destination_currency": "NGN",
    "amount": 50000,
    "reference": "5748745ug8ufdgjhveyebjhcdbchb",
    "status": "SUCCESSFUL",
    "bank": {
      "account_number": "0122333334",
      "code": "044",
      "branch": null,
      "name": null,
      "routing_number": null,
      "swift_code": null
    },
    "fee": {
      "currency": "NGN",
      "value": 500
    },
    "debit_information": {
      "currency": "NGN",
      "actual_debit_amount": 50000,
      "rate_used": 0.00123,
      "vat": 3750
    },
    "payment_information": {
      "proof": "504828363550713897092362940989"
    },
    "meta": {}
  }
}
```
```

--------------------------------

### Initiate COF Card Transaction (General)

Source: https://developer.flutterwave.com/docs/card

This example demonstrates how to initiate a COF card transaction by including the `COF` object with an `agreement_id` in the request payload.

```APIDOC
## POST /payment-methods

### Description
Initiates a Credential on File (COF) card transaction.

### Method
POST

### Endpoint
`https://developersandbox-api.flutterwave.com/payment-methods`

### Headers
- `Authorization`: `Bearer {{YOUR_ACCESS_TOKEN}}`
- `Content-Type`: `application/json`
- `X-Trace-Id`: `{{YOUR_UNIQUE_TRACE_ID}}`
- `X-Idempotency-Key`: `{{YOUR_UNIQUE_INDEMPOTENCY_KEY}}`

### Request Body
- `type` (string) - Required - Type of payment method, should be "card".
- `card` (object) - Required - Card details.
  - `encrypted_card_number` (string) - Required - Encrypted card number.
  - `encrypted_expiry_month` (string) - Required - Encrypted expiry month.
  - `encrypted_expiry_year` (string) - Required - Encrypted expiry year.
  - `encrypted_cvv` (string) - Required - Encrypted CVV.
  - `nonce` (string) - Required - Randomly generated nonce.
  - `cof` (object) - Required - COF details.
    - `enabled` (boolean) - Required - Set to `true` to enable COF.
    - `agreement_id` (string) - Required - Reference ID for the agreement.

### Request Example
```json
{
    "type": "card",
    "card": {
        "encrypted_card_number": "{{$encrypted_card_number}}",
        "encrypted_expiry_month": "{{$encrypted_expiry_month}}",
        "encrypted_expiry_year": "{{$encrypted_expiry_year}}",
        "encrypted_cvv": "{{$encrypted_cvv}}",
        "nonce": "{{$randomly_generated_nonce}}",
        "cof": {
                "enabled": true,
          	"agreement_id": "Agreement00w02W1"
            }
    }
}
```
```

--------------------------------

### Failed Transfer Due to Insufficient Balance

Source: https://developer.flutterwave.com/docs/testing

This example illustrates how to mock a failed transfer due to insufficient balance by using the `scenario:insufficient_balance` key.

```APIDOC
## POST /transfers

### Description
Mocks a failed transfer request due to insufficient balance.

### Method
POST

### Endpoint
https://developersandbox-api.flutterwave.com/transfers

### Headers
- Authorization: Bearer {{YOUR_ACCESS_TOKEN}}
- Content-Type: application/json
- X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}
- X-Scenario-Key: scenario:insufficient_balance

### Request Body
```json
{
  "action": "instant",
  "disburse_option": {
    "timezone": "Africa/Cairo"
  },
  "payment_instruction": {
    "source_currency": "USD",
    "amount": {
      "applies_to": "destination_currency",
      "value": 3500
    },
    "recipient_id": "rcb_aErW4535uiF8S"
  },
  "callback_url": "https://custom-redirect.com"
}
```

### Response
#### Error Response (400 Bad Request)
Indicates that there is insufficient balance for the transfer.

### Request Example
```bash
curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/transfers' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Scenario-Key: scenario:insufficient_balance' \
--data '{ "action": "instant", "disburse_option": { "timezone": "Africa/Cairo" }, "payment_instruction": { "source_currency": "USD", "amount": { "applies_to": "destination_currency", "value": 3500 }, "recipient_id": "rcb_aErW4535uiF8S" }, "callback_url": "https://custom-redirect.com" }'
```
```

--------------------------------

### Handle Redirect URL for Payment

Source: https://developer.flutterwave.com/docs/main-payment-flow

This is an example response indicating a redirect URL is required. The customer must be redirected to the provided URL to complete the payment.

```json
{
    "status": "success",
    "message": "Charge created",
    "data": {
        "id": "chg_RCDsCBDyaV",
        "...": "...",
        "next_action": {
            "type": "redirect_url",
            "redirect_url": {
                "url": "https://developer-sandbox-ui-sit.flutterwave.cloud/redirects?card&token=eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6ImFjODMxOTNlLWFhMmItNDc2ZS1hZTNjLTMxYmVmMTc4NDUxZCIsImNoYXJnZUlkIjoiY2hnX1JDRHNDQkR5YVYiLCJzdWIiOiJhYzgzMTkzZS1hYTJiLTQ3NmUtYWUzYy0zMWJlZjE3ODQ1MWQiLCJpYXQiOjE3MzA5NjQ1MTIsImV4cCI6MTczMDk2NDgxMn0.tMv1VZ4WevvZ_dg37AzYnhj0Z1YtXK_tQIOJcErNscI"
            }
        },
        "payment_method_details": {},
        "status": "pending",
        "...": "..."
    }
}
```

--------------------------------

### Fetch All Chargebacks - API Response

Source: https://developer.flutterwave.com/docs/chargebacks-1

This is an example of a successful response when fetching chargebacks. It includes details of accepted and declined chargebacks, along with metadata.

```json
{
    "status": "success",
    "message": "Chargebacks fetched",
    "meta": {
        "page_info": {
            "total": 2,
            "current_page": 1,
            "total_pages": 1
        }
    },
    "data": [
        {
            "id": "chb_KJ5rAYbkvt",
            "charge_id": "chg_RjxhF6IgxQ",
            "amount": 200,
            "meta": {},
            "stage": "new",
            "status": "accepted",
            "type": "local",
            "due_datetime": "2025-01-28T11:45:06.714Z",
            "created_datetime": "2025-01-27T11:45:06.715Z",
            "updated_datetime": "2025-01-27T11:45:31.190Z",
            "comment": "Chargeback accepted after review. Issue resolved in favor of the customer."
        },
        {
            "id": "chb_QYZyN5BBvE",
            "charge_id": "chg_Ppj3WCkVHk",
            "amount": 200,
            "meta": {},
            "stage": "new",
            "status": "declined",
            "type": "local",
            "due_datetime": "2025-01-28T10:13:41.845Z",
            "created_datetime": "2025-01-27T10:13:41.845Z",
            "updated_datetime": "2025-01-27T11:45:20.126Z",
            "uploaded_proof": "https://www.example-website.com/media/proof.png",
            "comment": "We provided value to the customer for the reported transaction. See image in proof for more information"
        }
    ]
}
```

--------------------------------

### Create a Customer with cURL

Source: https://developer.flutterwave.com/docs/opay

Use this cURL command to create a new customer. Ensure you replace placeholders like {{YOUR_ACCESS_TOKEN}} with your actual credentials. This is a prerequisite for initiating transactions.

```cURL
curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/customers' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{ \
   "address":{ \
      "city":"Shirley", \
      "country":"US", \
      "line1":"175 E Parkview Dr", \
      "line2":"", \
      "postal_code":"11967", \
      "state":"New York" \
   }, \
   "name":{ \
      "first":"John", \
      "middle":"Agba", \
      "last":"Doe" \
   }, \
   "phone":{ \
      "country_code":"1", \
      "number":"6313958745" \
   }, \
   "email":"Johndoe@example.com" \
}'
```

--------------------------------

### Get Banks API Response Example

Source: https://developer.flutterwave.com/docs/ussd

A successful response contains a list of bank objects, each with an ID, code, and name.

```json
{
  "status": "success",
  "message": "string",
  "data": [
    {
      "id": "bnk_cYjd92Qk",
      "code": "044",
      "name": "Access Bank"
    }
    ...
  ]
}
```

--------------------------------

### Create a Static Virtual Account

Source: https://developer.flutterwave.com/docs/pay-with-bank-transfer

Create a static virtual account using the customer ID obtained previously. Set the amount to 0 for static accounts as they are reusable. Include your access token and a unique idempotency key.

```curl
curl --location 'https://developersandbox-api.flutterwave.com/virtual-accounts' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--header 'Content-Type: application/json' \
--data '{ 
    "reference": "1ca9e18f-f038-436f-b32b-3b7facdb1e13",
    "customer_id": "cus_WWVaC0InrN",
    "amount": 0,
    "currency": "NGN",
    "account_type": "static",
    "narration": "Cornelius Ashley-Osuzoka",
    "bvn": "12345678901"
}'
```

--------------------------------

### Webhook Response Example

Source: https://developer.flutterwave.com/docs/direct-transfer-flow

This is an example of the JSON response Flutterwave sends to your webhook URL when a transfer is completed or fails. It provides real-time status updates.

```APIDOC
## Webhook Response

### Description
This is an example of the JSON response Flutterwave sends to your webhook URL when a transfer is completed or fails. It provides real-time status updates.

### Response Body
```json
{
  "webhook_id": "wbk_rp0bjKyAWA52ViM8xlZ0",
  "timestamp": 1739877172874,
  "type": "transfer.disburse",
  "data": {
    "id": "trf_yMZATJ11yVPNkZ",
    "type": "BANK",
    "source_currency": "NGN",
    "destination_currency": "NGN",
    "amount": 50000,
    "reference": "5748745ug8ufdgjhveyebjhcdbchb",
    "status": "SUCCESSFUL",
    "bank": {
      "account_number": "0122333334",
      "code": "044",
      "branch": null,
      "name": null,
      "routing_number": null,
      "swift_code": null
    },
    "fee": {
      "currency": "NGN",
      "value": 500
    },
    "debit_information": {
      "currency": "NGN",
      "actual_debit_amount": 50000,
      "rate_used": 0.00123,
      "vat": 3750
    },
    "payment_information": {
      "proof": "504828363550713897092362940989"
    },
    "meta": {}
  }
}
```
```

--------------------------------

### Create Customer

Source: https://developer.flutterwave.com/docs/pay-with-bank-transfer

Before creating a dynamic virtual account, you need to set up the customer object. This endpoint creates a new customer.

```APIDOC
## POST /customers

### Description
Creates a new customer.

### Method
POST

### Endpoint
https://developersandbox-api.flutterwave.com/customers

### Headers
- Content-Type: application/json
- Accept: application/json
- X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}
- Authorization: Bearer {{YOUR_ACCESS_TOKEN}}

### Request Body
- **name** (object) - Required - The name of the customer.
  - **first** (string) - Required - The first name.
  - **last** (string) - Required - The last name.
- **email** (string) - Required - The email address of the customer.

### Request Example
```json
{
  "name": {
    "first": "Cornelius",
    "last": "Ashley-Osuzoka"
  },
  "email": "cornelius@devxpay.com"
}
```

### Response
#### Success Response (201 Created)
- **status** (string) - The status of the operation.
- **message** (string) - A message describing the result.
- **data** (object) - The created customer object.
  - **id** (string) - The unique identifier for the customer.
  - **email** (string) - The customer's email.
  - **name** (object) - The customer's name.
    - **first** (string) - The first name.
    - **last** (string) - The last name.
  - **meta** (object) - Additional metadata.
  - **created_datetime** (string) - The date and time the customer was created.

#### Response Example
```json
{
    "status": "success",
    "message": "Customer created",
    "data": {
        "id": "cus_WWVaC0InrN",
        "email": "cornelius@devxpay.com",
        "name": {
            "first": "Cornelius",
            "last": "Ashley-Osuzoka"
        },
        "meta": {},
        "created_datetime": "2025-06-02T07:40:48.637002170Z"
    }
}
```
```

--------------------------------

### ZAR Bank Payout

Source: https://developer.flutterwave.com/docs/bank-transfer

Example of initiating a bank transfer from ZAR to ZAR.

```APIDOC
## POST /direct-transfers

### Description
Initiates a direct bank transfer.

### Method
POST

### Endpoint
https://developersandbox-api.flutterwave.com/direct-transfers

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token
- **Content-Type** (string) - Required - application/json
- **X-Trace-Id** (string) - Required - Unique trace ID
- **X-Idempotency-Key** (string) - Required - Unique idempotency key

#### Request Body
- **action** (string) - Required - Type of transfer (e.g., "instant", "scheduled", "deferred")
- **type** (string) - Required - Type of transfer (e.g., "bank")
- **callback_url** (string) - Required - URL for transfer callback
- **narration** (string) - Required - Description of the transfer
- **reference** (string) - Required - Unique reference for the transfer
- **payment_instruction** (object) - Required - Details of the payment
  - **amount** (object) - Required - Amount details
    - **value** (number) - Required - The amount value
    - **applies_to** (string) - Required - Currency to apply amount to (e.g., "destination_currency")
  - **source_currency** (string) - Required - Source currency code
  - **destination_currency** (string) - Required - Destination currency code
  - **recipient** (object) - Required - Recipient details
    - **type** (string) - Required - Recipient type (e.g., "bank")
    - **bank** (object) - Required - Bank details
      - **code** (string) - Required - Bank code
      - **account_number** (string) - Required - Recipient account number
    - **name** (object) - Required - Recipient name
      - **first** (string) - Required - First name
      - **middle** (string) - Optional - Middle name
      - **last** (string) - Required - Last name
    - **email** (string) - Optional - Recipient email
    - **phone** (object) - Optional - Recipient phone number
      - **country_code** (string) - Required - Country code
      - **number** (string) - Required - Phone number
    - **address** (object) - Optional - Recipient address
      - **line1** (string) - Required - Address line 1
      - **line2** (string) - Optional - Address line 2
      - **postal_code** (string) - Required - Postal code
      - **city** (string) - Required - City
      - **state** (string) - Required - State/Province
      - **country** (string) - Required - Country code

### Request Example
```json
{
  "action": "instant",
  "type": "bank",
  "callback_url": "https://www.company.com/callback",
  "narration": "Testing transfers",
  "reference": "{{YOUR_UNIQUE_REFERENCE}}",
  "payment_instruction": {
    "amount": {
      "value": 1000,
      "applies_to": "destination_currency"
    },
    "source_currency": "ZAR",
    "destination_currency": "ZAR",
    "recipient": {
      "type": "bank",
      "bank": {
        "code": "ABSA",
        "account_number": "1234567890"
      },
      "name": {
        "first": "Bob",
        "middle": "The",
        "last": "Builder"
      },
      "email": "user@example.com",
      "phone": {
        "country_code": "27",
        "number": "9012345678"
      },
      "address": {
        "line1": "7A, Awesome Apartments",
        "line2": "Sweet Street",
        "postal_code": "123456",
        "city": "Cool City",
        "state": "Super State",
        "country": "ZA"
      }
    }
  }
}
```
```

--------------------------------

### USD Bank Payout

Source: https://developer.flutterwave.com/docs/bank-transfer

Example of initiating a bank transfer from USD to USD.

```APIDOC
## POST /direct-transfers

### Description
Initiates a direct bank transfer.

### Method
POST

### Endpoint
https://developersandbox-api.flutterwave.com/direct-transfers

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token
- **Content-Type** (string) - Required - application/json
- **X-Trace-Id** (string) - Required - Unique trace ID
- **X-Idempotency-Key** (string) - Required - Unique idempotency key

#### Request Body
- **action** (string) - Required - Type of transfer (e.g., "instant", "scheduled", "deferred")
- **type** (string) - Required - Type of transfer (e.g., "bank")
- **callback_url** (string) - Required - URL for transfer callback
- **narration** (string) - Required - Description of the transfer
- **reference** (string) - Required - Unique reference for the transfer
- **payment_instruction** (object) - Required - Details of the payment
  - **amount** (object) - Required - Amount details
    - **value** (number) - Required - The amount value
    - **applies_to** (string) - Required - Currency to apply amount to (e.g., "destination_currency")
  - **source_currency** (string) - Required - Source currency code
  - **destination_currency** (string) - Required - Destination currency code
  - **recipient** (object) - Required - Recipient details
    - **type** (string) - Required - Recipient type (e.g., "bank")
    - **bank** (object) - Required - Bank details
      - **code** (string) - Required - Bank code
      - **account_number** (string) - Required - Recipient account number
      - **routing_number** (string) - Optional - Routing number
      - **swift_code** (string) - Optional - SWIFT code
      - **account_type** (string) - Optional - Account type (e.g., "checking")
    - **name** (object) - Required - Recipient name
      - **first** (string) - Required - First name
      - **middle** (string) - Optional - Middle name
      - **last** (string) - Required - Last name
    - **email** (string) - Optional - Recipient email
    - **phone** (object) - Optional - Recipient phone number
      - **country_code** (string) - Required - Country code
      - **number** (string) - Required - Phone number
    - **address** (object) - Optional - Recipient address
      - **line1** (string) - Required - Address line 1
      - **line2** (string) - Optional - Address line 2
      - **postal_code** (string) - Required - Postal code
      - **city** (string) - Required - City
      - **state** (string) - Required - State/Province
      - **country** (string) - Required - Country code

### Request Example
```json
{
  "action": "instant",
  "type": "bank",
  "callback_url": "https://www.company.com/callback",
  "narration": "Testing transfers",
  "reference": "{{YOUR_UNIQUE_REFERENCE}}",
  "payment_instruction": {
    "amount": {
      "value": 1000,
      "applies_to": "destination_currency"
    },
    "source_currency": "USD",
    "destination_currency": "USD",
    "recipient": {
      "type": "bank",
      "bank": {
        "code": "125200057",
        "routing_number": "021000021",
        "swift_code": "BOFAUS3N",
        "account_type": "checking",
        "account_number": "1234567890"
      },
      "name": {
        "first": "Bob",
        "middle": "The",
        "last": "Builder"
      },
      "email": "user@example.com",
      "phone": {
        "country_code": "1",
        "number": "9012345678"
      },
      "address": {
        "line1": "7A, Awesome Apartments",
        "line2": "Sweet Street",
        "postal_code": "123456",
        "city": "Cool City",
        "state": "Super State",
        "country": "US"
      }
    }
  }
}
```
```

--------------------------------

### Create a Customer

Source: https://developer.flutterwave.com/docs/pay-with-bank-transfer

Use this cURL command to create a customer object. Store the returned customer ID for creating virtual accounts. Ensure you include your unique idempotency key and access token.

```curl
curl --location 'https://developersandbox-api.flutterwave.com/customers' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--data-raw '{
  "name": {
    "first": "Cornelius",
    "last": "Ashley-Osuzoka"
  },
  "email": "cornelius@devxpay.com"
}'
```

--------------------------------

### EUR Bank Payout

Source: https://developer.flutterwave.com/docs/bank-transfer

Example request for initiating a bank transfer with EUR currency.

```APIDOC
## POST /direct-transfers

### Description
Initiates an instant bank transfer.

### Method
POST

### Endpoint
https://developersandbox-api.flutterwave.com/direct-transfers

### Headers
- Authorization: Bearer {{YOUR_ACCESS_TOKEN}}
- Content-Type: application/json
- X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}
- X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}

### Request Body
- action (string): "instant"
- type (string): "bank"
- callback_url (string): URL for callback notifications.
- narration (string): Description of the transfer.
- reference (string): Unique reference for the transfer.
- payment_instruction (object): Details of the payment.
  - amount (object): Amount details.
    - value (integer): The amount to transfer.
    - applies_to (string): "destination_currency" or "source_currency".
  - source_currency (string): Currency of the source account (e.g., EUR).
  - destination_currency (string): Currency of the destination account (e.g., EUR).
  - recipient (object): Details of the recipient.
    - bank (object): Bank details of the recipient.
      - code (string): Bank code.
      - account_number (string): Account number of the recipient.
    - name (object): Recipient's name.
      - first (string): First name.
      - middle (string): Middle name.
      - last (string): Last name.

### Request Example
```json
{
  "action": "instant",
  "type": "bank",
  "callback_url": "https://www.company.com/callback",
  "narration": "Testing transfers",
  "reference": "{{YOUR_UNIQUE_REFERENCE}}",
  "payment_instruction": {
    "amount": {
      "value": 1000,
      "applies_to": "destination_currency"
    },
    "source_currency": "EUR",
    "destination_currency": "EUR",
    "recipient": {
      "bank": {
        "code": "123",
        "account_number": "987654321"
      },
      "name": {
        "first": "Jane",
        "middle": "Doe",
        "last": "Smith"
      }
    }
  }
}
```
```

--------------------------------

### ETB Bank Payout

Source: https://developer.flutterwave.com/docs/bank-transfer

Example request for performing a bank transfer within ETB.

```APIDOC
## POST /direct-transfers

### Description
Initiates an instant bank transfer.

### Method
POST

### Endpoint
https://developersandbox-api.flutterwave.com/direct-transfers

### Headers
- Authorization: Bearer {{YOUR_ACCESS_TOKEN}}
- Content-Type: application/json
- X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}
- X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}

### Request Body
- action (string): "instant"
- type (string): "bank"
- callback_url (string): URL for callback notifications.
- narration (string): Description of the transfer.
- reference (string): Unique reference for the transfer.
- payment_instruction (object): Details of the payment.
  - amount (object): Amount details.
    - value (integer): The amount to transfer.
    - applies_to (string): "destination_currency" or "source_currency".
  - source_currency (string): Currency of the source account (e.g., ETB).
  - destination_currency (string): Currency of the destination account (e.g., ETB).
  - recipient (object): Details of the recipient.
    - bank (object): Bank details of the recipient.
      - code (string): Bank code.
      - account_number (string): Account number of the recipient.
    - name (object): Recipient's name.
      - first (string): First name.
      - middle (string): Middle name.
      - last (string): Last name.

### Request Example
```json
{
  "action": "instant",
  "type": "bank",
  "callback_url": "https://www.company.com/callback",
  "narration": "Testing transfers",
  "reference": "{{YOUR_UNIQUE_REFERENCE}}",
  "payment_instruction": {
    "amount": {
      "value": 1000,
      "applies_to": "destination_currency"
    },
    "source_currency": "ETB",
    "destination_currency": "ETB",
    "recipient": {
      "bank": {
        "code": "7",
        "account_number": "123456789"
      },
      "name": {
        "first": "Bob",
        "middle": "The",
        "last": "Builder"
      }
    }
  }
}
```
```

--------------------------------

### Customer Creation Response - JSON

Source: https://developer.flutterwave.com/docs/main-payment-flow

This is a sample successful response after creating a customer. It includes the unique customer ID and all the details provided in the request.

```json
{
    "status": "success",
    "message": "Customer created",
    "data": {
        "id": "cus_J0PvwvJB2n",
        "address": {
            "city": "Gotham",
            "country": "US",
            "line1": "221B Baker Street",
            "line2": "",
            "postal_code": "94105",
            "state": "Colorado"
        },
        "email": "james@example.com",
        "name": {
            "first": "King",
            "middle": "Leo",
            "last": "James"
        },
        "phone": {
            "country_code": "1",
            "number": "6313958745"
        },
        "meta": {},
        "created_datetime": "2024-12-03T13:54:21.546559974Z"
    }
}
```

--------------------------------

### Initiate OPay Charge

Source: https://developer.flutterwave.com/docs/opay

Initiate an OPay charge by sending a POST request to the create charge endpoint. Include the `customer_id`, `payment_method_id` obtained from previous steps, along with transaction details like `amount`, `currency`, and `reference`. Replace placeholders as needed.

```cURL
curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/charges' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{ \
   "currency":"NGN", \
   "customer_id":"cus_dc0FUyBpd0", \
   "payment_method_id":"pmd_uF9ADr9LvH", \
   "amount":200, \
   "reference":"ex61m23j6a3y0k34o9ilrri" \
}'
```

--------------------------------

### AUD Bank Payout

Source: https://developer.flutterwave.com/docs/bank-transfer

Example request for performing a bank transfer from USD to AUD.

```APIDOC
## POST /direct-transfers

### Description
Initiates an instant bank transfer.

### Method
POST

### Endpoint
https://developersandbox-api.flutterwave.com/direct-transfers

### Headers
- Authorization: Bearer {{YOUR_ACCESS_TOKEN}}
- Content-Type: application/json
- X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}
- X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}

### Request Body
- action (string): "instant"
- type (string): "bank"
- callback_url (string): URL for callback notifications.
- narration (string): Description of the transfer.
- reference (string): Unique reference for the transfer.
- payment_instruction (object): Details of the payment.
  - amount (object): Amount details.
    - value (integer): The amount to transfer.
    - applies_to (string): "destination_currency" or "source_currency".
  - source_currency (string): Currency of the source account (e.g., USD).
  - destination_currency (string): Currency of the destination account (e.g., AUD).
  - recipient (object): Details of the recipient.
    - bank (object): Bank details of the recipient.
      - routing_number (string): Routing number for the bank.
      - swift_code (string): SWIFT code of the bank.
      - name (string): Name of the bank.
      - account_number (string): Account number of the recipient.
    - name (object): Recipient's name.
      - first (string): First name.
      - middle (string): Middle name.
      - last (string): Last name.
    - email (string): Recipient's email address.
    - phone (object): Recipient's phone number.
      - country_code (string): Country code.
      - number (string): Phone number.
    - address (object): Recipient's address.
      - line1 (string): Address line 1.
      - line2 (string): Address line 2.
      - postal_code (string): Postal code.
      - city (string): City.
      - state (string): State.
      - country (string): Country code (e.g., AU).

### Request Example
```json
{
  "action": "instant",
  "type": "bank",
  "callback_url": "https://www.company.com/callback",
  "narration": "Testing transfers",
  "reference": "{{YOUR_UNIQUE_REFERENCE}}",
  "payment_instruction": {
    "amount": {
      "value": 1000,
      "applies_to": "destination_currency"
    },
    "source_currency": "USD",
    "destination_currency": "AUD",
    "recipient": {
      "bank": {
        "routing_number": "062123",
        "swift_code": "BANK123",
        "name": "Commonwealth Bank of Australia",
        "account_number": "123456789"
      },
      "name": {
        "first": "Bob",
        "middle": "The",
        "last": "Builder"
      },
      "email": "user@example.com",
      "phone": {
        "country_code": "61",
        "number": "9012345678"
      },
      "address": {
        "line1": "7A, Awesome Apartments",
        "line2": "Sweet Street",
        "postal_code": "123456",
        "city": "Cool City",
        "state": "Super State",
        "country": "AU"
      }
    }
  }
}
```
```

--------------------------------

### Get Bank Code

Source: https://developer.flutterwave.com/docs/managing-instant-loan-disbursements

Retrieve the bank code for a specific country to initiate payouts.

```APIDOC
## GET /banks

### Description
Retrieves a list of banks for a specified country. This is a prerequisite for initiating payouts to bank accounts.

### Method
GET

### Endpoint
/banks?country={country_code}

### Query Parameters
- **country** (string) - Required - The ISO 3166-1 alpha-2 country code (e.g., 'NG' for Nigeria).

### Request Example
```bash
curl --request GET \
     --url 'https://developersandbox-api.flutterwave.com/banks?country=NG' \
     --header 'X-Trace-Id: {{REPLACE_WITH_UNIQUE_IDENTIFIER}}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{REPLACE_WITH_API_ACCESS_TOKEN}}'
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation.
- **message** (string) - A message describing the result of the operation.
- **data** (array) - An array of bank objects.
  - **id** (string) - The unique identifier for the bank.
  - **code** (string) - The bank code.
  - **name** (string) - The name of the bank.

#### Response Example
```json
{
  "status": "success",
  "message": "Bank list retrieved successfully",
  "data": [
    {
      "id": "bnk_cYjd92Qk",
      "code": "044",
      "name": "Access Bank"
    }
  ]
}
```
```

--------------------------------

### Initiate Direct Charge with USSD

Source: https://developer.flutterwave.com/docs/payment-orchestrator-flow

This example demonstrates initiating a direct charge via USSD. You need to provide the account bank code for the USSD payment.

```json
curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/orchestration/direct-charges' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{ \
    "reference": "YOUR_EXAMPLE_REFERENCE", \
    "currency": "NGN", \
    "amount": 1234.56, \
    "payment_method": { \
        "type": "ussd", \
        "ussd": { \
            "account_bank":"044" \
        } \
    }, \
   "redirect_url":"http://www.custom-redirect.com", \
   "customer":{ \
      "address":{ \
        "country": "US", \
        "city": "Gotham", \
        "state": "Colorado", \
        "postal_code": "94105", \
        "line1": "221B Baker Street" \
      }, \
      "phone":{ \
         "country_code":"1", \
         "number":9069423351 \
      }, \
      "name":{ \
         "first": "King", \
         "middle": "Leo", \
         "last": "James" \
      }, \
      "email":"james@example.com" \
   }'
```

--------------------------------

### Get Banks

Source: https://developer.flutterwave.com/docs/ussd

Retrieve a list of supported banks for a specific country to display to the customer for selection.

```APIDOC
## GET /banks

### Description
Fetches a list of supported banks for a given country.

### Method
GET

### Endpoint
/banks

### Parameters
#### Query Parameters
- **country** (string) - Required - The country code (e.g., 'NG' for Nigeria) to filter banks.

### Response
#### Success Response (200)
- **data** (array) - A list of bank objects.
  - **id** (string) - The unique identifier for the bank.
  - **code** (string) - The bank's code.
  - **name** (string) - The name of the bank.

#### Response Example
```json
{
  "status": "success",
  "message": "string",
  "data": [
    {
      "id": "bnk_cYjd92Qk",
      "code": "044",
      "name": "Access Bank"
    }
  ]
}
```
```

--------------------------------

### Initiate a Test Chargeback

Source: https://developer.flutterwave.com/docs/chargebacks-1

Send a POST request to the create chargeback endpoint with the charge_id, amount, transaction type, and chargeback expiry. Ensure the charge_id matches a completed test payment and the amount is the full transaction amount. This endpoint is only available in Sandbox.

```json
{
  "charge_id": "chg_Ppj3WCkVHk",
  "amount": 200,
  "type": "local",
  "expiry": 24
}
```

--------------------------------

### Initiate a Direct Transfer

Source: https://developer.flutterwave.com/docs/introduction-3

Send the transfer reference, payment instruction, and transfer type to initiate the transfer. Ensure you include your access token, trace ID, and idempotency key.

```curl
curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/direct-transfers' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{ 
  "action": "instant",
  "payment_instruction": {
    "source_currency": "NGN",
    "amount": {
      "applies_to": "destination_currency",
      "value": 1000
    },
    "recipient": {
      "bank": {
        "account_number": "0122333334",
        "code": "044"
      }
    },
    "destination_currency": "NGN"
  },
  "type": "bank",
  "reference": "574874568ufdgjhvbjhcdbchb"
}'
```

```json
{
  "status": "success",
  "message": "Transfer created",
  "data": {
    "id": "trf_pGoKPGH7rEgY4v",
    "type": "bank",
    "reference": "574874568ufdgjhvbjhcdbchb",
    "status": "NEW",
    "source_currency": "NGN",
    "destination_currency": "NGN",
    "amount": {
      "value": 50000,
      "applies_to": "destination_currency"
    },
    "recipient": {
      "type": "bank",
      "bank": {
        "account_number": "0122333334",
        "code": "044"
      }
    },
    "meta": {},
    "created_datetime": "2024-12-05T12:36:20.069512926Z"
  }
}
```

```json
{
    "status": "failed",
    "error": {
        "type": "REFERENCE_ALREADY_EXISTS",
        "code": "201409",
        "message": "Transfer with reference already exists",
        "validation_errors": []
    }
}
```