Yellow Card Payments API

https://docs.yellowcard.engineering/docs/
Admin
Yellow Card's API provides comprehensive digital asset and fiat payment infrastructure for Africa...
Tokens:32,150
Snippets:228
Trust Score:5.1
Update:9 months ago
Show doc for...
Tokens:
Raw
### Get Asset Config Reference

Source: https://docs.yellowcard.engineering/docs/digital-asset-wallet-functionality

Retrieves the configuration for supported cryptocurrencies and their associated network details.

```APIDOC
## GET /asset/config

### Description
Retrieves a list of supported cryptocurrencies and their network configurations. This endpoint is useful for verifying if a specific digital asset is available for use and understanding its associated network parameters.

### Method
GET

### Endpoint
/asset/config

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **assets** (array) - An array of asset configuration objects.
  - **code** (string) - The unique code for the cryptocurrency (e.g., "USDC").
  - **resources** (array) - Links to relevant resources, such as whitepapers.
  - **zones** (array) - Categorization of the asset (e.g., "stablecoins").
  - **updatedAt** (string) - The timestamp of the last update.
  - **networks** (object) - An object containing supported network configurations for the asset.
  - **createdAt** (string) - The timestamp of asset creation.
  - **isUTXOBased** (boolean) - Indicates if the asset is UTXO-based.
  - **description** (string) - A detailed description of the cryptocurrency.
  - **id** (string) - The unique identifier for the asset.
  - **name** (string) - The full name of the cryptocurrency (e.g., "USD Coin").
  - **defaultNetwork** (string) - The default network for the asset (e.g., "ERC20").

#### Response Example
```json
[
  {
    "code": "USDC",
    "resources": [
      {
        "type": "file_url",
        "content": "https://f.hubspotusercontent30.net/hubfs/9304636/PDF/centre-whitepaper.pdf",
        "id": "WHITEPAPER"
      }
    ],
    "zones": [
      "stablecoins"
    ],
    "updatedAt": "2024-12-06T07:13:13.561Z",
    "networks": {},
    "createdAt": "2024-12-06T07:13:13.561Z",
    "isUTXOBased": false,
    "description": "USDC is a stablecoin, pegged 1:1 to the US$. Created by Circle & Coinbase, each USDC unit in circulation is backed by $1 held in reserve, consisting of a mix of cash and short-term U.S. Treasury bonds.<br /><br />Join the USDC ecosystem and enjoy the benefits of stability and peace of mind as you make digital transactions with confidence! 🛡️",
    "id": "usd-coin",
    "name": "USD Coin",
    "defaultNetwork": "ERC20"
  }
]
```

## GET /asset/networks

### Description
Retrieves a list of supported networks for various cryptocurrencies, detailing network-specific parameters such as address regular expressions, memo requirements, and transaction explorer URLs.

### Method
GET

### Endpoint
/asset/networks

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **networks** (object) - An object where keys are network identifiers (e.g., "XLM", "ERC20") and values are network configuration objects.
  - **nativeAsset** (string) - The native asset of the blockchain.
  - **chainCurrencyId** (string) - The identifier for the currency on the chain.
  - **addressRegex** (string) - The regular expression for validating wallet addresses.
  - **requiresMemo** (boolean) - Indicates if a memo is required for transactions.
  - **activities** (array) - Supported transaction activities (e.g., "SEND", "RECEIVE").
  - **explorerUrl** (string) - The URL for the blockchain explorer, with `__TX_HASH__` as a placeholder.
  - **name** (string) - The human-readable name of the network (e.g., "Stellar", "Ethereum").
  - **enabled** (boolean) - Indicates if the network is currently enabled.
  - **network** (string) - The network identifier.

#### Response Example
```json
{
  "XLM": {
    "nativeAsset": "XLM",
    "chainCurrencyId": "USDC",
    "addressRegex": "^G[A-Z2-7]{55}$",
    "requiresMemo": true,
    "activities": [
      "SEND",
      "RECEIVE"
    ],
    "explorerUrl": "https://blockchair.com/stellar/transaction/__TX_HASH__",
    "name": "Stellar",
    "enabled": true,
    "network": "XLM"
  },
  "SOL": {
    "nativeAsset": "SOL",
    "chainCurrencyId": "USDC",
    "addressRegex": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
    "requiresMemo": false,
    "activities": [
      "SEND",
      "RECEIVE"
    ],
    "explorerUrl": "https://explorer.solana.com/tx/__TX_HASH__",
    "name": "Solana",
    "enabled": true,
    "network": "SOL"
  }
}
```
```

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

### GET /channels

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

Retrieves a list of all available payment channels, including their supported countries, currencies, and transaction limits.

```APIDOC
## GET /channels

### Description
Retrieves a list of all available payment channels. This endpoint is crucial for integrators to understand which fiat ramps are available in the system at any given time, including supported countries and currencies.

### Method
GET

### Endpoint
/channels

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **channels** (array) - A list of channel objects.
  - **id** (string) - The unique identifier for the channel.
  - **country** (string) - The country supported by the channel.
  - **currency** (string) - The currency supported by the channel.
  - **channel_type** (string) - The type of channel (e.g., 'bank', 'momo', 'p2p', 'eft').
  - **ramp_type** (string) - The type of ramp (e.g., 'deposit', 'withdrawal').
  - **min_transaction_amount** (number) - The minimum transaction amount in the channel's local currency. 0 indicates no minimum.
  - **max_transaction_amount** (number) - The maximum transaction amount in the channel's local currency. 0 indicates no maximum specified by the provider (API default is 20,000 USD).

#### Response Example
```json
{
  "channels": [
    {
      "id": "602060c6-b4af-49a4-b8fd-2fdd0dbf13ce",
      "country": "Botswana",
      "currency": "BWP",
      "channel_type": "bank",
      "ramp_type": "deposit",
      "min_transaction_amount": 0,
      "max_transaction_amount": 0
    },
    {
      "id": "bf831f9d-75d2-4ee7-a44e-7c95be028bab",
      "country": "Botswana",
      "currency": "BWP",
      "channel_type": "momo",
      "ramp_type": "deposit",
      "min_transaction_amount": 0,
      "max_transaction_amount": 5000
    }
  ]
}
```

### Error Handling
- **404 Not Found**: If the resource does not exist.
- **500 Internal Server Error**: If there is a server-side error.
```

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

### Get Networks API

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

Lists available networks (e.g., Bank, Mobile Money) and reasons for sending funds.

```APIDOC
## GET /networks

### Description
Retrieves a list of available payment networks (e.g., Bank Transfer, Mobile Money) and a pre-defined list of reasons for sending payments.

### Method
GET

### Endpoint
/networks

### Query Parameters
- **country** (string) - Required - The country code for which to retrieve networks.

### Response
#### Success Response (200)
- **networks** (array) - A list of available payment networks.
  - **id** (string) - The unique identifier for the network.
  - **name** (string) - The name of the network (e.g., "Bank Transfer", "Mobile Money").
  - **fields** (array) - Fields required for this network (e.g., "bank_name", "account_number").
- **payment_reasons** (array) - A list of pre-defined reasons for sending the payment.

#### Response Example
```json
{
  "networks": [
    {
      "id": "bank",
      "name": "Bank Transfer",
      "fields": ["bank_name", "account_holder_name", "account_number"]
    },
    {
      "id": "mobile_money",
      "name": "Mobile Money",
      "fields": ["first_name", "last_name", "mobile_number", "mobile_provider"]
    }
  ],
  "payment_reasons": [
    "Salary Payment",
    "Business Transaction",
    "Gift"
  ]
}
```
```

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

### Get Rates API

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

Fetches exchange rates and limits for a specified payment channel and currency.

```APIDOC
## GET /rates

### Description
Retrieves the exchange rate for USD to a local fiat currency and the limits for a given payment channel.

### Method
GET

### Endpoint
/rates

### Query Parameters
- **country** (string) - Required - The country code for the desired fiat currency.
- **channel_id** (string) - Required - The ID of the payment channel.

### Response
#### Success Response (200)
- **rate** (number) - The current exchange rate (USD to local currency).
- **limits** (object) - Transaction limits for the specified channel.
  - **min** (number) - The minimum transaction amount.
  - **max** (number) - The maximum transaction amount.

#### Response Example
```json
{
  "rate": 450.50,
  "limits": {
    "min": 10.0,
    "max": 10000.0
  }
}
```
```

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

### GET /lookup-payment

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

Retrieves detailed information about a specific payment transaction.

```APIDOC
## GET /lookup-payment

### Description
Retrieves information about a specific payment transaction using its ID.

### Method
GET

### Endpoint
/lookup-payment

### Query Parameters
- **transaction_id** (string) - Required - The unique identifier for the transaction.

### Response
#### Success Response (200)
- **transaction_id** (string) - The unique identifier for the transaction.
- **status** (string) - The current status of the transaction (e.g., "COMPLETED", "FAILED", "PENDING").
- **amount_local** (number) - The amount in the local currency.
- **currency_from** (string) - The currency sent.
- **recipient_details** (object) - Details of the recipient.
- **created_at** (string) - Timestamp when the transaction was created.
- **updated_at** (string) - Timestamp when the transaction was last updated.

#### Response Example
```json
{
  "transaction_id": "txn_123abc456",
  "status": "COMPLETED",
  "amount_local": 10000.0,
  "currency_from": "USD",
  "recipient_details": {
    "bank_name": "Access Bank",
    "account_holder_name": "John Doe",
    "account_number": "1234567890"
  },
  "created_at": "2023-10-27T10:05:00Z",
  "updated_at": "2023-10-27T10:10:00Z"
}
```
```

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

### Create Webhook for All Events (JSON)

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

This example demonstrates how to create a webhook subscription that triggers for all available events. It requires a JSON payload containing the desired webhook URL and an 'active' status.

```json
{
  "url": "https://example.com/webhook",
  "active": true
}
```

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

### Create Webhook for Specific Event (JSON)

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

This example shows how to create a webhook subscription for a particular event, such as 'COLLECTION.COMPLETE'. The 'state' field must be prefixed with 'COLLECTION.' or 'PAYMENT.' to specify the event type.

```json
{
  "url": "https://example.com/webhook",
  "state": "COLLECTION.COMPLETE",
  "active": true
}
```

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

### Get Networks API

Source: https://docs.yellowcard.engineering/docs/api-glossary

List available financial networks (banks, mobile money operators) supported under each payment channel.

```APIDOC
## GET /networks

### Description
Retrieves a list of all available financial networks, such as banks and mobile network operators, that are supported within specific payment channels.

### Method
GET

### Endpoint
/networks

### Parameters
#### Path Parameters
None

#### Query Parameters
- **channel** (string) - Optional - Filters networks by a specific payment channel (e.g., 'mobile_money', 'bank_transfer').

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **networks** (array) - A list of network objects.
  - **id** (string) - The unique identifier for the network.
  - **name** (string) - The name of the network (e.g., 'Stanbic Bank Kenya', 'MTN Ghana').
  - **channel** (string) - The payment channel the network belongs to.

#### Response Example
```json
{
  "networks": [
    {
      "id": "net-stanbic-ke",
      "name": "Stanbic Bank Kenya",
      "channel": "bank_transfer"
    },
    {
      "id": "net-mtn-gh",
      "name": "MTN Ghana",
      "channel": "mobile_money"
    }
  ]
}
```
```

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

### Simulate Successful Crypto Send SettlementInfo Object

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

This JSON object shows the 'settlementInfo' for simulating a successful crypto send transaction. It includes the 'walletAddress', 'cryptoCurrency', and 'cryptoNetwork'. The wallet address used here is a success simulation address.

```JSON
"settlementInfo": {
    "walletAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "cryptoCurrency": "USDT",
    "cryptoNetwork": "TRC20"
  }
```

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

### Simulate Complete Mobile Money Collection Source Object

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

This JSON object illustrates the structure for simulating a complete mobile money collection. It specifies 'accountNumber', 'accountType' as 'momo', and 'networkId'. The 'accountNumber' uses a success test format.

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

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

### Supported Networks Configuration JSON

Source: https://docs.yellowcard.engineering/docs/digital-asset-wallet-functionality

This JSON object details the configuration for various supported cryptocurrency networks, including Stellar (XLM), Solana (SOL), Celo (CELO), Ethereum (ERC20), and Base (BASE). For each network, it specifies native asset, chain currency ID, address regex, memo requirements, supported activities, explorer URL, name, and enabled status.

```json
{
  "XLM": {
    "nativeAsset": "XLM",
    "chainCurrencyId": "USDC",
    "addressRegex": "^G[A-Z2-7]{55}$",
    "requiresMemo": true,
    "activities": [
      "SEND",
      "RECEIVE"
    ],
    "explorerUrl": "https://blockchair.com/stellar/transaction/__TX_HASH__",
    "name": "Stellar",
    "enabled": true,
    "network": "XLM"
  },
  "SOL": {
    "nativeAsset": "SOL",
    "chainCurrencyId": "USDC",
    "addressRegex": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
    "requiresMemo": false,
    "activities": [
      "SEND",
      "RECEIVE"
    ],
    "explorerUrl": "https://explorer.solana.com/tx/__TX_HASH__",
    "name": "Solana",
    "enabled": true,
    "network": "SOL"
  },
  "CELO": {
    "nativeAsset": "CELO",
    "chainCurrencyId": "USDC",
    "addressRegex": "^(0x)[0-9A-Fa-f]{40}$",
    "requiresMemo": false,
    "activities": [
      "SEND",
      "RECEIVE"
    ],
    "explorerUrl": "https://celoscan.io/tx/__TX_HASH__",
    "name": "Celo",
    "enabled": true,
    "network": "CELO"
  },
  "ERC20": {
    "nativeAsset": "ETH",
    "chainCurrencyId": "USDC",
    "addressRegex": "^(0x)[0-9A-Fa-f]{40}$",
    "requiresMemo": false,
    "activities": [
      "SEND",
      "RECEIVE"
    ],
    "explorerUrl": "https://etherscan.io/tx/__TX_HASH__",
    "name": "Ethereum",
    "enabled": true,
    "network": "ERC20"
  },
  "BASE": {
    "nativeAsset": "OP",
    "chainCurrencyId": "USDC",
    "addressRegex": "^(0x)[0-9A-Fa-f]{40}$",
    "requiresMemo": false,
    "activities": [
      "SEND",
      "RECEIVE"
    ],
    "explorerUrl": "https://basescan.org/tx/__TX_HASH__",
    "name": "Base",
    "enabled": true,
    "network": "BASE"
  }
}
```

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

### IP Address Whitelist

Source: https://docs.yellowcard.engineering/docs/authentication-api

In production environments, you are required to share your production server static IP addresses for whitelisting. The system authorizes requests only from whitelisted IP addresses.

```APIDOC
## IP Address Whitelist

### Description
In production environment, you're required to share with us your production server static IP address for whitelisting as we authorize requests from whitelisted IP addresses in production. We support whitelisting of IP range for both IPv4 and IPv6 addresses.

### Process
Contact the Yellowcard support team to provide your static IP addresses or IP ranges for whitelisting.
```

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

### Authentication

Source: https://docs.yellowcard.engineering/docs/authentication-api

Learn how to authenticate your API requests using API keys. Authenticated requests require specific headers for timestamp and authorization.

```APIDOC
## Authentication

### Description
Authenticated requests must include a `X-YC-Timestamp` header with the current timestamp in **ISO8601** format and an `Authorization` header in the `YcHmacV1` scheme, `Scheme {apikey}:{signature}`.

### Method
Any

### Endpoint
Any

### Headers
- **X-YC-Timestamp** (string) - Required - Current timestamp in ISO8601 format.
- **Authorization** (string) - Required - `YcHmacV1 {apikey}:{signature}`.

### Request Signing
The message to sign is a concatenation of:
  * The current datetime in **ISO8601** format
  * The request path (only path data, excluding host), e.g `/business/payments/accept`
  * The request method in caps, e.g _POST_
  * For _POST_ and _PUT_ requests a **base64** encoded **sha256** hash of the request body

**Example** message to sign, `2022-01-11T15:48:37.424Z/paymentPOSTuisbibf/sadf+==`.

### Request Example
```
{
  "X-YC-Timestamp": "2022-01-11T15:48:37.424Z",
  "Authorization": "YcHmacV1 aenifaieubgpa:fakno+9epoa/obe="
}
```

### Response
#### Success Response (200)
Response details depend on the specific endpoint called.

#### Response Example
```json
{
  "success": true
}
```
```

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

### Settlement API

Source: https://docs.yellowcard.engineering/docs/api-glossary

Submit a settlement request to programmatically pay out your balance. This process converts surplus Stablecoins back to local currency.

```APIDOC
## POST /settlements

### Description
Allows partners to programmatically pay out their balance to a pre-screened and whitelisted wallet address. This endpoint is used to finalize and move funds after transactions, effectively converting Stablecoins to local currency.

### Method
POST

### Endpoint
/settlements

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **source_wallet** (string) - Required - The wallet address from which to initiate the settlement (e.g., partner's USD settlement wallet).
- **destination_wallet** (string) - Required - The pre-whitelisted business wallet address for receiving the payout.
- **amount** (float) - Required - The amount of balance to settle.
- **currency** (string) - Required - The currency of the balance to settle (e.g., 'USD').
- **sequence_id** (string) - Required - A unique ID generated by the partner for idempotency.

### Request Example
```json
{
  "source_wallet": "0xSrcWalletAddress...",
  "destination_wallet": "0xDestWalletAddress...",
  "amount": 500.00,
  "currency": "USD",
  "sequence_id": "settle-tx-67890"
}
```

### Response
#### Success Response (200)
- **settlement_id** (string) - The unique identifier for the settlement transaction.
- **status** (string) - The status of the settlement (e.g., 'COMPLETED', 'PROCESSING').

#### Response Example
```json
{
  "settlement_id": "settle-1a2b3c4d5e",
  "status": "PROCESSING"
}
```
```

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

### POST /submit-payment-request

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

Submits a payment request with all necessary details to initiate a transaction.

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

### Description
Submits a payment request with recipient details, amount, and selected payment channel to get a quote for the payment.

### Method
POST

### Endpoint
/submit-payment-request

### Request Body
- **destination_country** (string) - Required - The country code of the recipient.
- **amount_local** (number) - Required - The amount to be sent in the local currency.
- **currency_from** (string) - Required - The currency to send from (e.g., "USD").
- **payment_channel_id** (string) - Required - The ID of the chosen payment channel.
- **network_id** (string) - Required - The ID of the chosen payment network.
- **recipient_details** (object) - Required - Details of the recipient based on the network.
  - *(Fields vary based on network_id, e.g., account_number, mobile_number)*
- **reason** (string) - Required - The reason for sending the payment.

### Request Example
```json
{
  "destination_country": "NG",
  "amount_local": 10000.0,
  "currency_from": "USD",
  "payment_channel_id": "bank_transfer",
  "network_id": "bank",
  "recipient_details": {
    "bank_name": "Access Bank",
    "account_holder_name": "John Doe",
    "account_number": "1234567890"
  },
  "reason": "Salary Payment"
}
```

### Response
#### Success Response (200)
- **quote_id** (string) - A unique identifier for the payment quote.
- **total_amount_local** (number) - The total amount to be paid in local currency, including fees.
- **rate** (number) - The exchange rate used for the conversion.
- **expires_at** (string) - The timestamp when the quote expires.

#### Response Example
```json
{
  "quote_id": "q_abc123xyz",
  "total_amount_local": 10150.0,
  "rate": 450.50,
  "expires_at": "2023-10-27T10:00:00Z"
}
```
```

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

### Simulate Failed Bank Payment Destination Object

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

This JSON object demonstrates the structure for simulating a failed bank payment. It includes key fields like accountNumber, accountType, and networkId. The 'accountNumber' is set to a failure test number.

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

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

### USDC Asset Configuration JSON

Source: https://docs.yellowcard.engineering/docs/digital-asset-wallet-functionality

This JSON object represents the configuration for the USDC stablecoin, including its ID, name, description, and associated resources like a whitepaper. It also indicates that it is not UTXO-based and specifies the default network as ERC20.

```json
[
  {
    "code": "USDC",
    "resources": [
      {
        "type": "file_url",
        "content": "https://f.hubspotusercontent30.net/hubfs/9304636/PDF/centre-whitepaper.pdf",
        "id": "WHITEPAPER"
      }
    ],
    "zones": [
      "stablecoins"
    ],
    "updatedAt": "2024-12-06T07:13:13.561Z",
    "networks": {},
    "createdAt": "2024-12-06T07:13:13.561Z",
    "isUTXOBased": false,
    "description": "USDC is a stablecoin, pegged 1:1 to the US$. Created by Circle & Coinbase, each USDC unit in circulation is backed by $1 held in reserve, consisting of a mix of cash and short-term U.S. Treasury bonds.<br /><br />Join the USDC ecosystem and enjoy the benefits of stability and peace of mind as you make digital transactions with confidence! 🛡️",
    "id": "usd-coin",
    "name": "USD Coin",
    "defaultNetwork": "ERC20"
  }
]
```

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

### Direct Settlement Collection Request Example

Source: https://docs.yellowcard.engineering/docs/direct-settlement

This JSON object represents a sample request payload for initiating a direct settlement collection. It includes recipient and source details, settlement information, and flags to enable direct settlement and force acceptance.

```json
{
  "recipient": {
    "name": "John Doe",
    "country": "Nigeria",
    "phone": "+2349092916898",
    "address": "Home Address, Sea of tranquility, Moon",
    "dob": "02/01/1997",
    "idNumber": "314159",
    "idType": "license"
  },
  "source": {
    "accountType": "bank",
    "accountNumber": "1111111111" 
  },
  "channelId": "af944f0c-ba70-47c7-86dc-1bad5a6ab4e4",
  "sequenceId": "53f7c7fa-f2bb-450c-8f6d-9ff0000f99",
  "amount": 50,
  "currency": "NGN",
  "country": "NG",
  "reason": "other",
  "forceAccept": true,
  "directSettlement": true,
  "settlementInfo": {
    "walletAddress": "TFtbBrsWw5DGHoKQE8VY2WzTY3VnanQ2hz", 
    "cryptoCurrency": "USDT", 
    "cryptoNetwork": "TRC20"
  }
}
```

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

### Simulate Failed Crypto Send SettlementInfo Object

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

This JSON object represents the 'settlementInfo' for simulating a failed crypto send transaction. It contains 'walletAddress', 'cryptoCurrency', and 'cryptoNetwork'. The wallet address specified is one of the designated failure simulation addresses.

```JSON
"settlementInfo": {
    "walletAddress": "TFvde3D6NQrjXrjqUsdwLTCvVhdPDYEBRV",
    "cryptoCurrency": "USDT",
    "cryptoNetwork": "TRC20"
  }
```

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

### Direct Settlement Collection Response Example

Source: https://docs.yellowcard.engineering/docs/direct-settlement

This JSON object demonstrates a sample response payload after a direct settlement collection request. It provides transaction status, settlement details including crypto rates and amounts, fee information, and banking details for deposit.

```json
{
   "currency": "NGN",
    "settlementInfo": {
      "cryptoNetwork": "TRC20",
      "cryptoLocalRate": 1617.3,
      "cryptoUSDRate": 1,
      "walletAddress": "TFtbBrsWw5DGHoKQE8VY2WzTY3VnanQ2hz", 
      "cryptoAmount": 48.36654808,
      "cryptoCurrency": "USDT"
   },
   "status": "processing",
   "networkFeeAmountUSD": 1.13, 
   "serviceFeeAmountUSD": 0.5,
   "partnerFeeAmountLocal": 0,
   "country": "NG",
   "reference": "JJ5275168",
   "recipient": {
   "country": "Nigeria",
   "address": "Home Address",
   "idType": "license",
   "phone": "+23490XXXXXXXX",
   "dob": "02/01/1997",
   "name": "John Doe",
   "idNumber": "314159"
   },
   "expiresAt": "2024-11-26T21:05:13.393Z",
   "requestSource": "api",
   "directSettlement": true,
   "refundRetry": 0,
   "id": "0a89dce0-d8d2-59a6-ab9d-1d9d8b4593e2",
   "partnerId": "9ecf5248-17e7-4a2b-b5a8-3bd58ff0fe01",
   "rate": 1617.3,
   "bankInfo": {  
     "name": "PAGA",
     "accountNumber": "4550440202",
     "accountName": "Ken Adams"
   },
   "createdAt": "2024-11-26T20:55:13.393Z",
   "forceAccept": true,
   "source": {
     "accountNumber": "1111111111",
     "accountType": "bank"
   },
   "sequenceId": "53f7c7fa-f2bb-450c-8f6d-9ff0000f7",
   "reason": "other",
   "networkFeeAmountLocal": 1833.13,
   "convertedAmount": 80865,
   "channelId": "af944f0c-ba70-47c7-86dc-1bad5a6ab4e4",
   "serviceFeeAmountLocal": 808.65,
   "updatedAt": "2024-11-26T20:55:17.487Z",
   "partnerFeeAmountUSD": 0,
   "amount": 50,
   "depositId": "a29e596a-0ae5-4386-b2a3-eacf9fc70575"
}
```

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

### Webhook Management

Source: https://docs.yellowcard.engineering/docs/api-glossary

Partners can register a webhook URL to receive real-time notifications from Yellow Card about various events.

```APIDOC
## POST /webhooks

### Description
Registers a webhook URL with Yellow Card. This allows your server to receive automated, server-to-server notifications (callbacks) when specific events occur within the Yellow Card system, such as payment confirmations or KYC status changes.

### Method
POST

### Endpoint
/webhooks

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL on your server where Yellow Card should send webhook notifications.
- **events** (array) - Optional - A list of specific events to subscribe to. If not provided, all events may be sent.
  - **event_name** (string) - The name of the event (e.g., 'payment.accepted', 'kyc.status.changed').

### Request Example
```json
{
  "url": "https://your-app.com/api/yellowcard-webhook",
  "events": [
    "payment.accepted",
    "payment.failed"
  ]
}
```

### Response
#### Success Response (200)
- **webhook_id** (string) - The unique identifier for the registered webhook.
- **url** (string) - The registered webhook URL.
- **status** (string) - The status of the webhook (e.g., 'ACTIVE').

#### Response Example
```json
{
  "webhook_id": "wh-xyz789",
  "url": "https://your-app.com/api/yellowcard-webhook",
  "status": "ACTIVE"
}
```

## DELETE /webhooks/{webhook_id}

### Description
Unregisters a previously registered webhook URL using its unique identifier.

### Method
DELETE

### Endpoint
/webhooks/{webhook_id}

### Parameters
#### Path Parameters
- **webhook_id** (string) - Required - The unique identifier of the webhook to unregister.

#### Query Parameters
None

### Request Example
(No request body for DELETE requests)

### Response
#### Success Response (204)
No Content. Indicates successful deletion.

#### Response Example
(No response body for a 204 No Content response)
```

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

### Payment Request API

Source: https://docs.yellowcard.engineering/docs/api-glossary

Create a disbursement by submitting a payment request. This action locks in an exchange rate for the desired amount and must be accepted within a time limit to avoid expiration.

```APIDOC
## POST /business/payments

### Description
Creates a disbursement by initiating a payment request. This locks in an exchange rate for the specified amount and requires acceptance before it expires.

### Method
POST

### Endpoint
/business/payments

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (float) - Required - The amount to be disbursed.
- **currency** (string) - Required - The currency of the amount (e.g., 'USD').
- **recipient_address** (string) - Required - The destination wallet address for the payout.
- **sequence_id** (string) - Required - A unique ID generated by the partner for idempotency.

### Request Example
```json
{
  "amount": 100.50,
  "currency": "USD",
  "recipient_address": "0x123...abc",
  "sequence_id": "partner-tx-12345"
}
```

### Response
#### Success Response (200)
- **payment_request_id** (string) - The unique identifier for the created payment request.
- **status** (string) - The status of the payment request (e.g., 'PENDING').
- **expires_at** (string) - The timestamp when the payment request expires.

#### Response Example
```json
{
  "payment_request_id": "pr-abcdef123456",
  "status": "PENDING",
  "expires_at": "2023-10-27T10:00:00Z"
}
```
```

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

### Generate Deposit Address

Source: https://docs.yellowcard.engineering/docs/digital-asset-wallet-functionality

Generates a unique deposit address for a specified cryptocurrency within a customer's vault.

```APIDOC
## POST /vaults/{vaultId}/deposit-address

### Description
Generates a new deposit address for a given cryptocurrency within a specified vault. This address can then be shared with customers for them to send digital assets from external wallets.

### Method
POST

### Endpoint
/vaults/{vaultId}/deposit-address

### Parameters
#### Path Parameters
- **vaultId** (string) - Required - The unique identifier of the vault.

#### Query Parameters
- **assetCode** (string) - Required - The code of the cryptocurrency for which to generate the deposit address (e.g., "USDC").

### Request Example
None (Request body is typically empty for this operation, parameters are in path and query)

### Response
#### Success Response (200)
- **address** (string) - The newly generated deposit address.
- **assetCode** (string) - The code of the cryptocurrency for the generated address.
- **network** (string) - The network on which the address is generated.
- **memo** (string, optional) - The memo associated with the address, if required.

#### Response Example
```json
{
  "address": "GDABCDEFG1234567890abcdefghijklmnopqrstuvwxyzABCDEFG",
  "assetCode": "USDC",
  "network": "XLM",
  "memo": "123456789"
}
```
```

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

### Reduced KYC (Tier 0) Metadata (JSON)

Source: https://docs.yellowcard.engineering/docs/kyc-metadata

Minimal KYC metadata required for eligible retail transactions meeting specific criteria. This includes name, country, and email, bypassing full KYC requirements.

```json
{
  "name": "Sample Name",  
  "country": "KE",  
  "email": "email@domain.com"
}
```

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

### POST /accept-payment-request

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

Accepts a previously submitted payment request quote to finalize the transaction.

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

### Description
Accepts a payment request quote to initiate the payment process.

### Method
POST

### Endpoint
/accept-payment-request

### Request Body
- **quote_id** (string) - Required - The ID of the payment quote to accept.

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

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

#### Response Example
```json
{
  "transaction_id": "txn_123abc456",
  "status": "PENDING"
}
```
```
Tokens:
Raw