Yellowcard Engineering

https://docs.yellowcard.engineering/v1.1.0/docs/
Admin
Yellowcard Engineering provides technical documentation detailing the development, architecture, and...
Tokens:38,939
Snippets:194
Trust Score:5.1
Update:9 months ago
Show doc for...
Tokens:
Raw
### Sandbox Testing - Collection Simulation

Source: https://docs.yellowcard.engineering/v1.1.0/docs/sandbox-testing-api

Provides an example of a source object for simulating a complete mobile money collection request.

```APIDOC
## Sandbox Testing - Collection Simulation

### Description
Provides an example of a source object for simulating a complete mobile money collection request.

### Request Example (Collection Simulation)
```json
{
  "source": {
    "accountNumber": "+2341111111111",
    "accountType": "momo",
    "networkId": "20823163-f55c-4fa5-8cdb-d59c5289a137"
  }
}
```
```

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

### Sandbox Testing - Disbursement Simulation

Source: https://docs.yellowcard.engineering/v1.1.0/docs/sandbox-testing-api

Provides an example of a destination object for simulating a failed bank disbursement request.

```APIDOC
## Sandbox Testing - Disbursement Simulation

### Description
Provides an example of a destination object for simulating a failed bank disbursement request.

### Request Example (Disbursement Simulation)
```json
{
    "destination": {
        "accountName": "Regina Phalenge",
        "accountNumber": "0000000000",
        "accountType": "bank",
        "networkId": "5f1af11b-305f-4420-8fce-65ed2725a409"
    }
}
```
```

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

### Create Webhook API Request Example

Source: https://docs.yellowcard.engineering/v1.1.0/docs/webhooks-api

This example illustrates how to make an API request to create a webhook. It shows the necessary JSON payload, including fields like `url`, `apiKey`, and optionally `event` and `active`. If the `state` field is omitted during creation, the webhook will trigger for all events. The `active` field defaults to `true` if not specified.

```javascript
const axios = require('axios');

async function createWebhook(webhookUrl, apiKey, eventState) {
  const payload = {
    url: webhookUrl,
    apiKey: apiKey
  };
  if (eventState) {
    payload.event = eventState;
  }

  try {
    const response = await axios.post('https://api.yellowcard.co/v1/webhooks', payload, {
      headers: {
        'Authorization': `Bearer YOUR_API_TOKEN` // Replace with your actual API token
      }
    });
    console.log('Webhook created successfully:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error creating webhook:', error.response ? error.response.data : error.message);
    throw error;
  }
}

// Example usage:
// const webhookUrl = 'https://your-callback-url.com/webhook';
// const apiKey = 'YOUR_API_KEY';
// createWebhook(webhookUrl, apiKey, 'COLLECTION.COMPLETE'); // For a specific event
// createWebhook(webhookUrl, apiKey); // For all events
```

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

### GET /channels

Source: https://docs.yellowcard.engineering/v1.1.0/docs/channels-api

Retrieves a list of all available financial channels, their status, and supported countries and currencies. This endpoint is crucial for integrators to understand the available fiat ramps.

```APIDOC
## GET /channels

### Description
Retrieves a list of all available financial channels, their status, and supported countries and currencies. This endpoint is crucial for integrators to understand the available fiat ramps.

### Method
GET

### Endpoint
/channels

### Parameters
#### Query Parameters
- **country** (string) - Optional - Filters channels by a specific country.
- **currency** (string) - Optional - Filters channels by a specific currency.
- **channel_type** (string) - Optional - Filters channels by a specific channel type (e.g., `bank`, `momo`, `p2p`, `eft`).

### Request Example
```
GET /channels?country=NG&channel_type=p2p
```

### Response
#### Success Response (200)
- **channels** (array) - A list of channel objects.
  - **id** (string) - The unique identifier for the channel.
  - **country** (string) - The country where the channel is active.
  - **currency** (string) - The currency supported by the channel.
  - **channel_type** (string) - The type of channel (e.g., `bank`, `momo`).
  - **payment_method** (string) - The specific payment method facilitated by the channel.
  - **settlement_time** (string) - The estimated settlement time for transactions.
  - **min_transaction_amount** (number) - The minimum transaction amount allowed for this channel, in the channel's local currency.
  - **max_transaction_amount** (number) - The maximum transaction amount allowed for this channel, in the channel's local currency. If 0, it implies no provider-defined maximum, and a default API maximum of 20,000 USD is applied.

#### Response Example
```json
{
  "channels": [
    {
      "id": "af944f0c-ba70-47c7-86dc-1bad5a6ab4e4",
      "country": "NG",
      "currency": "NGN",
      "channel_type": "p2p",
      "payment_method": "Bank Transfer",
      "settlement_time": "Instant",
      "min_transaction_amount": 1000,
      "max_transaction_amount": 0
    },
    {
      "id": "bf831f9d-75d2-4ee7-a44e-7c95be028bab",
      "country": "BW",
      "currency": "BWP",
      "channel_type": "momo",
      "payment_method": "Mobile Money",
      "settlement_time": "Instant",
      "min_transaction_amount": 50,
      "max_transaction_amount": 5000
    }
  ]
}
```
```

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

### Get Available Networks and Reasons

Source: https://docs.yellowcard.engineering/v1.1.0/docs/disbursement-user-journey

Retrieves a list of available networks (e.g., mobile providers) and pre-defined reasons for sending funds, used when entering recipient details.

```APIDOC
## GET /api/v1/networks-reasons

### Description
Retrieves lists of available networks (e.g., mobile providers for mobile money) and predefined reasons for the transaction. This helps in populating dropdowns for user input.

### Method
GET

### Endpoint
`/api/v1/networks-reasons`

### Parameters
#### Query Parameters
- **country_code** (string) - Required - The ISO 3166-1 alpha-2 country code.
- **payment_channel_id** (string) - Required - The ID of the selected payment channel.

### Request Example
```
GET /api/v1/networks-reasons?country_code=NG&payment_channel_id=mobile_money_mtn
```

### Response
#### Success Response (200)
- **networks** (array) - A list of available networks for the given channel and country.
  - **id** (string) - The network identifier.
  - **name** (string) - The network name.
- **reasons** (array) - A list of pre-defined reasons for the transaction.
  - **id** (string) - The reason identifier.
  - **description** (string) - The description of the reason.

#### Response Example
```json
{
  "networks": [
    {
      "id": "mtn_ng",
      "name": "MTN Nigeria"
    },
    {
      "id": "glo_ng",
      "name": "Glo Nigeria"
    }
  ],
  "reasons": [
    {
      "id": "personal_remittance",
      "description": "Personal Remittance"
    },
    {
      "id": "family_support",
      "description": "Family Support"
    }
  ]
}
```
```

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

### Accept Payment Request

Source: https://docs.yellowcard.engineering/v1.1.0/docs/disbursement-user-journey

Accepts a previously submitted payment request quote to initiate the actual withdrawal process. This is the final step to start the conversion.

```APIDOC
## POST /api/v1/accept-payment-request

### Description
Accepts a payment request quote to initiate the crypto-to-fiat withdrawal. This action finalizes the transaction based on the provided quote.

### Method
POST

### Endpoint
`/api/v1/accept-payment-request`

### Parameters
#### Request Body
- **quote_id** (string) - Required - The ID of the payment quote obtained from the submit payment request endpoint.

### Request Example
```json
{
  "quote_id": "quote_abc123xyz"
}
```

### Response
#### Success Response (200)
- **transaction_id** (string) - A unique identifier for the initiated transaction.
- **status** (string) - The current status of the transaction (e.g., 'processing').

#### Response Example
```json
{
  "transaction_id": "txn_def456uvw",
  "status": "processing"
}
```
```

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

### Get Withdrawal Limits and Rates

Source: https://docs.yellowcard.engineering/v1.1.0/docs/disbursement-user-journey

Fetches the withdrawal limits and the current exchange rate for converting a specific amount of USD to local fiat currency for a chosen payment channel.

```APIDOC
## GET /api/v1/rates-limits

### Description
Retrieves the withdrawal limits and the current exchange rate for a given amount and payment channel. This helps users understand transaction constraints and conversion values.

### Method
GET

### Endpoint
`/api/v1/rates-limits`

### Parameters
#### Query Parameters
- **country_code** (string) - Required - The ISO 3166-1 alpha-2 country code.
- **payment_channel_id** (string) - Required - The ID of the selected payment channel.
- **amount_usd** (number) - Required - The amount in USD the user wishes to withdraw.

### Request Example
```
GET /api/v1/rates-limits?country_code=NG&payment_channel_id=bank_transfer&amount_usd=100
```

### Response
#### Success Response (200)
- **limits** (object) - Information about withdrawal limits.
  - **min_usd** (number) - The minimum amount that can be withdrawn in USD.
  - **max_usd** (number) - The maximum amount that can be withdrawn in USD.
- **rate** (number) - The current exchange rate for USD to the local currency.
- **total_local_amount** (number) - The total amount in local currency after conversion.

#### Response Example
```json
{
  "limits": {
    "min_usd": 10,
    "max_usd": 10000
  },
  "rate": 750.50,
  "total_local_amount": 75050.00
}
```
```

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

### Get Available Payment Channels

Source: https://docs.yellowcard.engineering/v1.1.0/docs/disbursement-user-journey

Retrieves a list of payment channels available for a given country, allowing users to see options like bank transfer and mobile money for withdrawals.

```APIDOC
## GET /api/v1/payment-channels

### Description
Retrieves a list of available payment channels for a specified country. This endpoint is used to display withdrawal options to the user.

### Method
GET

### Endpoint
`/api/v1/payment-channels`

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

### Request Example
```
GET /api/v1/payment-channels?country_code=NG
```

### Response
#### Success Response (200)
- **channels** (array) - A list of available payment channels.
  - **id** (string) - The unique identifier for the payment channel.
  - **name** (string) - The display name of the payment channel (e.g., 'Bank Transfer', 'Mobile Money').
  - **type** (string) - The type of the payment channel (e.g., 'bank', 'mobile_money').

#### Response Example
```json
{
  "channels": [
    {
      "id": "bank_transfer",
      "name": "Bank Transfer",
      "type": "bank"
    },
    {
      "id": "mobile_money_mtn",
      "name": "MTN Mobile Money",
      "type": "mobile_money"
    }
  ]
}
```
```

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

### Retrieve Rates Data (JSON Example)

Source: https://docs.yellowcard.engineering/v1.1.0/docs/using-rates-data

This snippet demonstrates the expected JSON structure when requesting rates data from the API. It includes details such as buy/sell rates, locale, rate ID, currency code, and update timestamp. The 'buy' and 'sell' fields are crucial as they represent the local currency to USD exchange rate.

```json
{
    "rates": [
				{
            "buy": 569.48,
            "locale": "NG",
            "rateId": "naira",
            "code": "NGN",
            "updatedAt": "2021-12-30T09:13:54.544Z"
        }
    ]
}
```

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

### Sandbox Testing - Test Account Numbers

Source: https://docs.yellowcard.engineering/v1.1.0/docs/sandbox-testing-api

This section lists the test account numbers available for simulating different transaction outcomes in the sandbox environment.

```APIDOC
## Sandbox Testing - Test Account Numbers

### Description
This section lists the test account numbers available for simulating different transaction outcomes in the sandbox environment.

### Test Account Numbers
*   **Success Bank Account Number**: `1111111111`
*   **Failure Bank Account Number**: `0000000000`
*   **Success Mobile Money Account Number**: `+{countryCode}1111111111` (e.g., `+2341111111111`)
*   **Failure Mobile Money Account Number**: `+{countryCode}0000000000` (e.g., `+2340000000000`)
```

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

### Rates and Supported Crypto Assets

Source: https://docs.yellowcard.engineering/v1.1.0/docs/api-endpoints-widget

Fetch current exchange rates and information about supported cryptocurrency assets.

```APIDOC
## GET /rates

### Description
Retrieves current exchange rates and details of supported crypto assets.

### Method
GET

### Endpoint
`/rates`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```
GET /rates
```

### Response
#### Success Response (200)
- **rates** (object) - An object containing current exchange rates for supported assets.
- **supported_assets** (array) - A list of supported cryptocurrency assets.
```

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

### Supported Currencies & Payment Methods

Source: https://docs.yellowcard.engineering/v1.1.0/docs/api-endpoints-widget

Retrieve information about supported currencies and payment methods available through the API.

```APIDOC
## GET /channels & GET /networks

### Description
Retrieves a list of supported channels and networks for transactions.

### Method
GET

### Endpoint
`/channels`
`/networks`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```
GET /channels
GET /networks
```

### Response
#### Success Response (200)
- **channels** (array) - List of supported payment channels.
- **networks** (array) - List of supported blockchain networks.
```

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

### Get Rates Data

Source: https://docs.yellowcard.engineering/v1.1.0/docs/using-rates-data

Retrieve current currency exchange rates. The rates are provided in terms of the local currency to the United States Dollar.

```APIDOC
## GET /rates

### Description
Retrieves a list of currency exchange rates. The `buy` and `sell` fields indicate the rate at which the end user will buy and sell the given currency. This rate is always the local currency to the United States Dollar.

### Method
GET

### Endpoint
/rates

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```
GET /rates
```

### Response
#### Success Response (200)
- **rates** (array) - An array of currency rate objects.
  - **buy** (number) - The rate at which a user will buy the currency.
  - **locale** (string) - The locale code for the currency.
  - **rateId** (string) - The identifier for the rate.
  - **code** (string) - The currency code.
  - **updatedAt** (string) - The timestamp when the rate was last updated.

#### Response Example
```json
{
    "rates": [
				{
            "buy": 569.48,
            "locale": "NG",
            "rateId": "naira",
            "code": "NGN",
            "updatedAt": "2021-12-30T09:13:54.544Z"
        }
    ]
}
```
```

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

### Widget Query Parameters

Source: https://docs.yellowcard.engineering/v1.1.0/docs/parameters-widget

This section outlines the various query parameters that can be used to pre-populate fields within the Yellowcard widget, enabling a more streamlined user experience. Remember to URL-encode parameter values when necessary.

```APIDOC
## GET /websites/yellowcard_engineering_v1_1_0

### Description
Pre-populate fields in the Yellowcard widget with gathered information using URL query parameters.

### Method
GET

### Endpoint
/websites/yellowcard_engineering_v1_1_0

### Parameters
#### Query Parameters
- **currencyAmount** (string) - Optional - The amount in `local currency` which the customer wants to transact. e.g. `10000`. If this is provided, the amount field will be **uneditable**.
- **cryptoAmount** (string) - Optional - The amount of `cryptocurrency` which the customer wants to transact e.g. `12`. If this is provided, then the crypto amount field will be populated and **uneditable**. Note that this only works if `txType=sell` is passed as well.
- **txType** (string) - Optional - Default tab to open the widget with and disables switching between tabs. `buy` opens the buy tab and `sell` opens the sell tab. If a value isn't passed, it defaults to the buy tab.
- **token** (string) - Optional - The asset to be transacted. If this is passed in, then the token dropdown is **uneditable**. Options are `USDC`, `BTC`, `ETH`, `USDT`.
- **walletAddress** (string) - Optional - The address to be used in a widget buy transaction. If this field is provided, then it is expected that the `token` and `signature` fields are also provided else the widget is not going to load properly.If this field is provided, then the address field is populated and **uneditable**.
- **localCurrency** (string) - Optional - The local currency to select when the widget is loaded. If this parameter is passed, the field will not be editable for currencies that are neither `XAF` nor `XOF`. However, for `XAF` and `XOF`, the currency may be editable depending on whether the `country` parameter is passed as well.
- **country** (string) - Optional - The 2-letter country code signifying the country for the currency to be selected. This only takes effect when the `localCurrency` is `XOF` or `XAF`.
- **network** (string) - Optional - Some tokens have multiple networks available, e.g. `USDC` is available on `ERC20` and `CELO` network. Valid options include `ERC20`, `TRC20`, `CELO`, `BTC`. If no network is specified, our default network will be assigned to the token. If an invalid network is specified, our default network will be assigned to the token. Supported crypto and network guide is available here.
- **email** (string) - Optional - The email address of the user. This value must be url-encoded. e.g. `test%2Bsomething%40yellowcard.io`
- **firstname** (string) - Optional - The first name(s) of the user. If more than one name is given they should be added to this parameter seperated by a space. If more than one name is given this value should be url-encoded. e.g.`James%20Earl`
- **lastname** (string) - Optional - The last name of the user. e.g. `Jones`
- **day** (string) - Optional - The day of birth of the user. This number should be passed as a 2-digit string, e.g. `08`
- **month** (string) - Optional - The month of birth of the user. This number should be passed as a 2-digit string, e.g. `04`
- **year** (string) - Optional - The year of birth of the user. This number should be a 4-digit string, e.g. `1988`
- **phone** (string) - Optional - The phone number of the user. This number excludes the country code and should not contain spaces. e.g. `0768940938`
- **street** (string) - Optional - The street address of the user. This value should be url-encoded. e.g. `56%20Darling%20Street`
- **state** (string) - Optional - The state in which the user resides. This value is from a predefined list, please see this section for options. e.g. `Adamawa`
- **city** (string) - Optional - The city in which the user resides. This value is. from a predefined list, please see this section for options. e.g. `Gombi`
- **postalCode** (string) - Optional - The postal code of the user's residence. e.g. `8453`
- **sourceOfFunds** (string) - Optional - Where the user receives funds from to perform this transaction. These values are from a predefined list. Options are `Salary`, `Savings`, `Proceeds from business transactions`, `Inheritance`, `Winnings`. If more than one option is passed, it should be passed in seperate query parameters. This value should be url-encoded if there are spaces. e.g. `&sourceOfFunds=Salary&sourceOfFunds=Savings&sourceOfFunds=Winnings&sourceOfFunds=Proceeds%20from%20business%20transactions`
- **otherSourceOfFunds** (string) - Optional - Any other potential sources of funds, passed as a string. e.g. `Found%20it%20on%20the%20floor`
- **walletAddress** (string) - Optional - The wallet address of the user where the funds will be transferred to. If this value is passed through it will be **uneditable** in the widget and **must** be accompanied by `token` and `signature`. e.g. `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`
- **channelId** (string) - Optional - The ID of the Yellowcard channel through which the fiat funds will be deposited. This is akin to payment method, and can be determined by the GET CHANNELS endpoint. e.g. `af944f0c-ba70-47c7-86dc-1bad5a6ab4e4`
- **channelType** (string) - Optional - The type of Yellowcard channel through which the fiat funds will be transferred. Valid values for this field are `momo` or `bank`. If no value is supplied then the user will pick their own channel on the relevant widget screen.

### Request Example
```
GET /websites/yellowcard_engineering_v1_1_0?currencyAmount=10000&token=USDC&email=test%2Bsomething%40yellowcard.io&firstname=James%20Earl&lastname=Jones&day=08&month=04&year=1988&phone=0768940938&street=56%20Darling%20Street&state=Adamawa&city=Gombi&postalCode=8453&sourceOfFunds=Salary&sourceOfFunds=Savings&otherSourceOfFunds=Found%20it%20on%20the%20floor&walletAddress=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t&channelId=af944f0c-ba70-47c7-86dc-1bad5a6ab4e4&channelType=momo
```

### Response
#### Success Response (200)
This endpoint typically returns a redirect to the widget with the pre-populated fields. No specific JSON response body is usually returned for a successful pre-population.

#### Response Example
(Redirect to widget URL with query parameters applied)
```

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

### Webhook Data Structure Example

Source: https://docs.yellowcard.engineering/v1.1.0/docs/webhooks-widget

This JSON object represents the data structure of events sent to webhooks. It includes details about the transaction, event type, and associated API key.

```json
{
  "id": "00e97bc4-1429-4ce7-acb5-841f9d9ed059",
  "sequenceId": "1a051f68-5c55-44c8-b4a0-366800daaf19",
  "status": "settlement_complete",
  "apiKey": "513fc4c3aaeb2a8f292a740ea178d830",
  "event": "COLLECTION.SETTLEMENT_COMPLETE",
  "executedAt": "2023-02-20T14:25:30.459Z",
  "settlementInfo": {
    "cryptoAmount": 8.29,
    "cryptoCurrency": "USDT",
    "txHash": "e057148a02fb41ebbb00734591d148ca069670ec16824c85414c581c850af9df",
    "cryptoLocalRate": 1030.55,
    "cryptoNetwork": "TRC20",
    "cryptoUSDRate": 1,
    "walletAddress": "TCFda5ggmJ8YuziS3vTt49f11uEzGSL4Jl",
    "senderAddress": "TCFda5ggmJ8YuziS3vTt49f11uEzGSL4Ji"

 }
}
```

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

### Refund and Cancellation Statuses

Source: https://docs.yellowcard.engineering/v1.1.0/docs/cancellation-refunds-collection-requests

Details the possible statuses for refund and cancellation processes, along with their descriptions.

```APIDOC
## Refund and Cancellation Statuses

### Refund Statuses

| Status          | Description                                                                                                                                   |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `pending_refund`  | Refund request is received and is currently being processed, waiting for feedback from the payment provider.                                  |
| `refunded`        | Refund is complete; the fund has been received by the customer.                                                                               |
| `refund_failed`   | The refund attempt has failed after multiple retries (5 attempts). It is advisable to retry after a few hours.                               |

> **Note on Failed Refunds:** If a refund fails, the system will retry up to 5 times. If it continues to fail, it is advisable to retry after a few hours. If `refund_failed` persists after multiple attempts, contact support. This often occurs due to banking network issues in Nigeria.

### Cancellation Statuses

| Status      | Description                                                                                                     |
|-------------|-----------------------------------------------------------------------------------------------------------------|
| `cancelled` | The collection request has been cancelled. If a deposit is received after cancellation, it will be refunded. |

```

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

### Simulate Complete Mobile Money Collection (JSON)

Source: https://docs.yellowcard.engineering/v1.1.0/docs/sandbox-testing-api

This JSON object illustrates the structure of a source account for simulating a complete mobile money collection. It specifies the account number, type, and network ID.

```json
{
  "source": {
    "accountNumber": "+2341111111111",
    "accountType": "momo",
    "networkId": "20823163-f55c-4fa5-8cdb-d59c5289a137"
  }
}
```

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

### Simulate Failed Bank Disbursement (JSON)

Source: https://docs.yellowcard.engineering/v1.1.0/docs/sandbox-testing-api

This JSON object demonstrates the structure of a destination account for simulating a failed bank disbursement. It includes account details like name, number, type, and network ID.

```json
{
    "destination": {
        "accountName": "Regina Phalenge",
        "accountNumber": "0000000000",
        "accountType": "bank",
        "networkId": "5f1af11b-305f-4420-8fce-65ed2725a409"
    }
}
```

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

### Yellowcard Environments

Source: https://docs.yellowcard.engineering/v1.1.0/docs/environments-api

Details the endpoints for the Yellowcard API across different environments.

```APIDOC
## Yellowcard API Environments

### Description
This section details the base endpoints for accessing the Yellowcard API in different deployment environments.

### Method
GET

### Endpoint
N/A (Informational)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Environment** (string) - Name of the environment (e.g., Sandbox Server, Production Server)
- **Endpoint** (string) - The base URL for the API in that environment

#### Response Example
```json
{
  "Environments": [
    {
      "Environment": "Sandbox Server",
      "Endpoint": "https://sandbox.api.yellowcard.io/business"
    },
    {
      "Environment": "Production Server",
      "Endpoint": "https://api.yellowcard.io/business"
    }
  ]
}
```
```

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

### KYC and Transaction Parameters

Source: https://docs.yellowcard.engineering/v1.1.0/docs/parameters-widget

This section details the parameters used for Know Your Customer (KYC) checks and transaction processing, including identification types, numbers, and redirect link management.

```APIDOC
## POST /api/transactions (Example Endpoint)

### Description
This endpoint is used to initiate a transaction, requiring customer identification details and optional redirect information.

### Method
POST

### Endpoint
/api/transactions

### Parameters
#### Query Parameters
- **idType** (string) - Required - The type of identification document. Should be url-encoded if it contains a slash.
- **idNumber** (string) - Required - The number on the identification document.
- **additionalIdType** (string) - Optional - The type of identification document when an additional ID is required (e.g., BVN for Nigeria).
- **additionalIdNumber** (string) - Optional - The number on the identification document (e.g., BVN number for Nigeria).
- **sequenceId** (string) - Required - A unique ID provided by you to track the order.
- **redirectLink** (string) - Optional - The URL the customer will be directed to upon completion. Must be url-encoded and start with https://. Overwrites partner config redirect URL.
- **redirectLinkSignature** (string) - Required if redirectLink is provided - The sha256 hash to verify the redirectLink. Must be url-encoded.

#### Request Body
*This endpoint does not explicitly define a request body in the provided text. Parameters are expected as query parameters.*

### Request Example
```
POST /api/transactions?idType=NIN%20Slip%2FCard&idNumber=YOUR_NIN_NUMBER&additionalIdType=BVN&additionalIdNumber=YOUR_BVN_NUMBER&sequenceId=7a03dfc8-ccc4-4350-a28f-be038edf3cc4&redirectLink=https%3A%2F%2Fexample.com%2Fcallback&redirectLinkSignature=YOUR_SIGNATURE
```

### Response
#### Success Response (200)
*The success response details are not provided in the input text.*

#### Response Example
```json
{
  "status": "success",
  "transactionId": "txn_12345"
}
```

## Multi-country Currency Support

### Description
This section describes how the widget handles multi-country currencies like XAF and XOF, including default selection and customer modification behavior.

### Method
N/A (Configuration/Behavioral)

### Endpoint
N/A

### Parameters
* **localCurrency** (string) - Optional - Specifies the local currency. If XAF or XOF is used, it may be selectable by the customer unless a specific country is also provided.
* **country** (string) - Optional - Specifies the country. If provided with `localCurrency`, the currency is fixed for that country.

### Notes
- If `localCurrency` is XAF or XOF, the widget selects a currency if the partner has a rate. The customer can change it.
- If both `localCurrency` and `country` are provided, the correct currency for the country is selected, and the customer cannot change it.

## IdType and AdditionalIdType - Nigeria

### Description
Specific instructions for providing Nigerian KYC details (NIN and BVN) using `idType`, `idNumber`, `additionalIdType`, and `additionalIdNumber` parameters.

### Method
N/A (Parameter Convention)

### Endpoint
N/A

### Parameters
- **idType** (string) - Required - Set to `NIN Slip/Card` for Nigerian NIN.
- **idNumber** (string) - Required - The customer's NIN number.
- **additionalIdType** (string) - Required for Nigerian KYC - Set to `BVN`.
- **additionalIdNumber** (string) - Required for Nigerian KYC - The customer's BVN number.

> Note: `idType` needs to be url-encoded.

## City and State Mapping

### Description
Provides the required combinations for `city` and `state` parameters to ensure correct dropdown population in the widget.

### Method
N/A (Data Mapping)

### Endpoint
N/A

### Parameters
* **city** (string) - Required - The city name.
* **state** (string) - Required - The state name.

### Notes
The `city` and `state` parameters must adhere to specific documented combinations for the dropdowns to function correctly. Refer to the full documentation for the mapping.
```

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

### 3.5 Re-direct Integration

Source: https://docs.yellowcard.engineering/v1.1.0/docs/re-direct-widget

Integrates with Yellowcard by redirecting customers to a hosted webpage for transactions. This method is suitable for both desktop and mobile applications.

```APIDOC
## GET /landing/{yourApiKey}

### Description
This endpoint facilitates a redirect integration where users are sent to a hosted Yellowcard webpage to initiate transactions. It's designed for simplicity on both desktop and mobile platforms.

### Method
GET

### Endpoint
`https://sandbox--payments-widget.netlify.app/landing/{yourApiKey}`

### Parameters
#### Path Parameters
- **yourApiKey** (string) - Required - Your unique API key to authenticate the request.

#### Query Parameters
- **txType** (string) - Optional - Specifies the default widget tab to display. Accepted values are `buy` or `sell`. If omitted, the widget defaults to the `buy` tab.

### Request Example
```
https://sandbox--payments-widget.netlify.app/landing/YOUR_API_KEY?txType=sell
```

### Response
#### Success Response (302 Found)
This endpoint initiates a redirect. A successful response will typically involve an HTTP 302 Found status code, redirecting the user's browser to the specified URL.

#### Response Example
*(Browser will be redirected, no JSON response body)*
```

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

### Submit Payment Request

Source: https://docs.yellowcard.engineering/v1.1.0/docs/disbursement-user-journey

Initiates a withdrawal request by submitting recipient details, amount, and other necessary information. Returns a quote for the transaction.

```APIDOC
## POST /api/v1/submit-payment-request

### Description
Submits a withdrawal request with all required recipient and transaction details. This endpoint confirms the user's intent to proceed with the withdrawal and provides a quote.

### Method
POST

### Endpoint
`/api/v1/submit-payment-request`

### Parameters
#### Request Body
- **country_code** (string) - Required - The ISO 3166-1 alpha-2 country code.
- **payment_channel_id** (string) - Required - The ID of the selected payment channel.
- **amount_usd** (number) - Required - The amount in USD to withdraw.
- **recipient_details** (object) - Required - Details of the recipient.
  - **first_name** (string) - Required (for mobile money) - Recipient's first name.
  - **last_name** (string) - Required (for mobile money) - Recipient's last name.
  - **bank_name** (string) - Required (for bank transfer) - Name of the recipient's bank.
  - **account_number** (string) - Required (for bank transfer) - Recipient's bank account number.
  - **mobile_number** (string) - Required (for mobile money) - Recipient's mobile number (including country code).
  - **network_id** (string) - Required (for mobile money) - The ID of the mobile network provider.
  - **reason_id** (string) - Required - The ID of the reason for the transfer.

### Request Example
```json
{
  "country_code": "NG",
  "payment_channel_id": "bank_transfer",
  "amount_usd": 100,
  "recipient_details": {
    "bank_name": "First Bank of Nigeria",
    "account_number": "1234567890",
    "reason_id": "personal_remittance"
  }
}
```

### Response
#### Success Response (200)
- **quote_id** (string) - A unique identifier for the transaction quote.
- **total_local_amount** (number) - The final amount in local currency, including any fees.
- **exchange_rate** (number) - The exchange rate used for the conversion.
- **valid_until** (string) - The timestamp until which the quote is valid.

#### Response Example
```json
{
  "quote_id": "quote_abc123xyz",
  "total_local_amount": 75050.00,
  "exchange_rate": 750.50,
  "valid_until": "2023-10-27T10:00:00Z"
}
```
```

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

### Generate HMAC Signature for Order Request (JavaScript)

Source: https://docs.yellowcard.engineering/v1.1.0/docs/parameters-widget

This snippet demonstrates how to generate a SHA256 HMAC signature for an order request. It requires a secret key and a JSON object containing the wallet address and token. The resulting signature must be URL-encoded.

```javascript
const crypto = require('crypto');

const walletAddress = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
const token = 'USDT'

const message = {
    address: walletAddress,
    token: token,
}

const secretKey = '8a2bfda7f762403b97a3abddc9c16c9298d066f81b7d01679c918929528f969c'

const signature = crypto
    .createHmac('sha256', secretKey)
    .update(JSON.stringify(message))
    .digest('base64');

console.log(encodeURIComponent(signature))
```

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

### POST /collections/{id}/refund

Source: https://docs.yellowcard.engineering/v1.1.0/docs/cancellation-refunds-collection-requests

Initiates a refund for a collection request. This endpoint is available for collection requests in Nigeria via Peer to Peer bank transfers. A successful request indicates the refund is being processed.

```APIDOC
## POST /collections/{id}/refund

### Description
Initiates a refund for a collection request. This is only available in Nigeria for collection requests made through Peer to Peer bank transfers. A `200` response indicates the refund is being processed.

### Method
POST

### Endpoint
`{baseUrl}/collections/{id}/refund`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the collection request to be refunded.

### Request Body
This endpoint does not require a request body.

### Response
#### Success Response (200)
- **message** (string) - Indicates that the refund is being processed.

#### Response Example
```json
{
  "message": "Refund is being processed."
}
```

#### Error Responses
- **400** - Validation error if the collection is not in a state that allows refunds (`complete` or `cancelled` status).
- **500** - Server error.
```

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

### Nigerian States and Cities Data Structure (JavaScript)

Source: https://docs.yellowcard.engineering/v1.1.0/docs/parameters-widget

This snippet defines a JavaScript object representing Nigerian states and their corresponding cities. It's likely used for address selection or geographical data management. The structure is a list of objects, each with a state name and an array of cities.

```javascript
{
  name: 'Anambra',
  cities: [
    'Aniocha South',
    'Bomadi',
    'Burutu',
    'Ethiope East',
    'Ethiope West',
    'Ika North East',
    'Ika South',
    'Isoko North',
    'Isoko South',
    'Ndokwa East',
    'Ndokwa West',
    'Okpe',
    'Oshimili North',
    'Oshimili South',
    'Patani',
    'Sapele',
    'Udu',
    'Ughelli North',
    'Ughelli South',
    'Ukwuani',
    'Uvwie',
    'Warri North',
    'Warri South',
    'Warri South West',
  ]
},
{
  name: 'Ebonyi',
  cities: [
    'Afikpo North',
    'Afikpo South',
    'Ebonyi',
    'Ezza North',
    'Ezza South',
    'Ikwo',
    'Ishielu',
    'Ivo',
    'Izzi',
    'Ohaozara',
    'Ohaukwu',
    'Onicha',
  ]
},
{
  name: 'Edo',
  cities: [
    'Egor',
    'Esan Central',
    'Esan North-East',
    'Esan South-East',
    'Esan West',
    'Etsako Central',
    'Etsako East',
    'Etsako West',
    'Igueben',
    'Ikpoba Okha',
    'Orhionmwon',
    'Oredo',
    'Ovia North-East',
    'Ovia South-West',
    'Owan East',
    'Owan West',
    'Uhunmwonde',
  ]
},
{
  name: 'Ekiti',
  cities: [
    'Efon',
    'Ekiti East',
    'Ekiti South-West',
    'Ekiti West',
    'Emure',
    'Gbonyin',
    'Ido Osi',
    'Ijero',
    'Ikere',
    'Ikole',
    'Ilejemeje',
    'Irepodun/Ifelodun',
    'Ise/Orun',
    'Moba',
    'Oye',
  ]
},
{
  name: 'Enugu',
  cities: [
    'Awgu',
    'Enugu East',
    'Enugu North',
    'Enugu South',
    'Ezeagu',
    'Igbo Etiti',
    'Igbo Eze North',
    'Igbo Eze South',
    'Isi Uzo',
    'Nkanu East',
    'Nkanu West',
    'Nsukka',
    'Oji River',
    'Udenu',
    'Udi',
    'Uzo Uwani',
  ]
},
{
  name: 'FCT',
  cities: [
    'Bwari',
    'Gwagwalada',
    'Kuje',
    'Kwali',
    'Municipal Area Council',
  ]
},
{
  name: 'Gombe',
  cities: [
    'Balanga',
    'Billiri',
    'Dukku',
    'Funakaye',
    'Gombe',
    'Kaltungo',
    'Kwami',
    'Nafada',
    'Shongom',
    'Yamaltu/Deba',
  ]
},
{
  name: 'Imo',
  cities: [
    'Ahiazu Mbaise',
    'Ehime Mbano',
    'Ezinihitte',
    'Ideato North',
    'Ideato South',
    'Ihitte/Uboma',
    'Ikeduru',
    'Isiala Mbano',
    'Isu',
    'Mbaitoli',
    'Ngor Okpala',
    'Njaba',
    'Nkwerre',
    'Nwangele',
    'Obowo',
    'Oguta',
    'Ohaji/Egbema',
    'Okigwe',
    'Orlu',
    'Orsu',
    'Oru East',
    'Oru West',
    'Owerri Municipal',
    'Owerri North',
    'Owerri West',
    'Unuimo',
  ]
},
{
  name: 'Jigawa',
  cities: [
    'Babura',
    'Biriniwa',
    'Birnin Kudu',
    'Buji',
    'Dutse',
    'Gagarawa',
    'Garki',
    'Gumel',
    'Guri',
    'Gwaram',
    'Gwiwa',
    'Hadejia',
    'Jahun',
    'Kafin Hausa',
    'Kazaure',
    'Kiri Kasama',
    'Kiyawa',
    'Kaugama',
    'Maigatari',
    'Malam Madori',
    'Miga',
    'Ringim',
    'Roni',
    'Sule Tankarkar',
    'Taura',
    'Yankwashi',
  ]
},
{
  name: 'Kaduna',
  cities: [
    'Chikun',
    'Giwa',
    'Igabi',
    'Ikara',
    'Jaba',
    'Jema\'a',
    'Kachia',
    'Kaduna North',
    'Kaduna South',
    'Kagarko',
    'Kajuru',
    'Kaura',
    'Kauru',
    'Kubau',
    'Kudan',
    'Lere',
    'Makarfi',
    'Sabon Gari',
    'Sanga',
    'Soba',
    'Zangon Kataf',
    'Zaria',
  ]
},
{
  name: 'Kano',
  cities: [
    'Gabasawa',
    'Garko',
    'Garun Mallam',
    'Gaya',
    'Gezawa',
    'Gobarawa',
    'Gwarzo',
    'Kabo',
    'KADUNA SOUTH',
    'Karaye',
    'Kiyawa',
    'Kuchi',
    'Kura',
    'Kwallafawa',
    'Lantana',
    'Madobi',
    'Makoda',
    'Minjibir',
    'Nasarawa',
    'Rano',
    'Rimin Gado',
    'Sabo',
    'Sumaila',
    'Takai',
    'Tandama',
    'Tofa',
    'Tsanyawa',
    'Tudun Wada',
    'Ungogo',
    'Warawa',
    'Wudil',
  ]
}
```
Tokens:
Raw