Skip to main content
POST
/
fiat-collections
curl -X POST https://secureapi.gridlog.io/api/v1/fiat-collections \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "localAmount": 200000,
    "currency": "NGN",
    "country": "NG",
    "recipient": {
      "name": "Sandbox User",
      "country": "NG",
      "phone": "+2348012345678",
      "address": "123 Sandbox Street, Lagos",
      "dob": "1990-01-01",
      "idNumber": "0123456789",
      "idType": "NIN"
    },
    "settlementInfo": {
      "walletAddress": "ALTJjFXGgAEHtKnyctUgVzkJujkR7mjKU6G7uLPycBUe",
      "cryptoCurrency": "USDT",
      "cryptoNetwork": "SOL"
    },
    "source": {
      "accountType": "bank",
      "accountNumber": "1111111111"
    },
    "reason": "other"
  }'

{
  "id": "0a89dce0-d8d2-59a6-ab9d-1d9d8b4593e2",
  "status": "processing",
  "amount": "200000.00",
  "currency": "NGN",
  "country": "NG",
  "bankInfo": {
    "name": "PAGA",
    "accountNumber": "4550440202",
    "accountName": "Ken Adams"
  },
  "settlementInfo": {
    "walletAddress": "ALTJjFXGgAEHtKnyctUgVzkJujkR7mjKU6G7uLPycBUe",
    "cryptoCurrency": "USDT",
    "cryptoNetwork": "SOL",
    "cryptoAmount": "121.45"
  },
  "rate": "1617.300000",
  "networkFeeUsd": "1.130000",
  "serviceFeeUsd": "0.500000",
  "convertedAmount": "200000.00",
  "expiresAt": "2025-03-21T21:05:13.393Z",
  "ycReference": "JJ5275168",
  "sequenceId": "53f7c7fa-f2bb-450c-8f6d-9ff0000f99",
  "createdAt": "2025-03-21T20:55:13.393Z"
}
Initiates a fiat collection. YellowCard returns bank account details where the customer deposits fiat. Once the deposit is confirmed, YellowCard converts the fiat and sends crypto (USDC/USDT) to the specified wallet address. Requires autosweep to be enabled for the business.

​
Authentication

This endpoint supports both API key (X-API-Key header) and Bearer token (Authorization: Bearer <JWT>) authentication.

​
Amount fields

You must provide either amount or localAmount — not both:
FieldDescription
amountUSD amount. YellowCard calculates the local currency equivalent using partner rates.
localAmountLocal currency amount (e.g., NGN). This fixes the fiat amount the customer pays, and the USD/crypto equivalent is calculated.
​
amount
number
USD amount to collect. Provide this or localAmount — not both. YellowCard will calculate the local currency equivalent based on partner rates.
​
localAmount
number
Local currency amount to collect (e.g., 200000 for 200,000 NGN). Provide this or amount — not both. This fixes the fiat amount the customer pays.
​
currency
string
required
ISO 4217 fiat currency code (e.g., "NGN", "KES", "GHS")
​
country
string
required
ISO 3166-1 alpha-2 country code (e.g., "NG", "KE", "GH")
​
recipient
object
required
Recipient KYC information
​
settlementInfo
object
required
Crypto settlement destination
​
source
object
Source bank account info
​
channelId
string
YellowCard channel ID. Auto-selected if not provided.
​
reason
string
Reason for the collection (default: "other")
curl -X POST https://secureapi.gridlog.io/api/v1/fiat-collections \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "localAmount": 200000,
    "currency": "NGN",
    "country": "NG",
    "recipient": {
      "name": "Sandbox User",
      "country": "NG",
      "phone": "+2348012345678",
      "address": "123 Sandbox Street, Lagos",
      "dob": "1990-01-01",
      "idNumber": "0123456789",
      "idType": "NIN"
    },
    "settlementInfo": {
      "walletAddress": "ALTJjFXGgAEHtKnyctUgVzkJujkR7mjKU6G7uLPycBUe",
      "cryptoCurrency": "USDT",
      "cryptoNetwork": "SOL"
    },
    "source": {
      "accountType": "bank",
      "accountNumber": "1111111111"
    },
    "reason": "other"
  }'

{
  "id": "0a89dce0-d8d2-59a6-ab9d-1d9d8b4593e2",
  "status": "processing",
  "amount": "200000.00",
  "currency": "NGN",
  "country": "NG",
  "bankInfo": {
    "name": "PAGA",
    "accountNumber": "4550440202",
    "accountName": "Ken Adams"
  },
  "settlementInfo": {
    "walletAddress": "ALTJjFXGgAEHtKnyctUgVzkJujkR7mjKU6G7uLPycBUe",
    "cryptoCurrency": "USDT",
    "cryptoNetwork": "SOL",
    "cryptoAmount": "121.45"
  },
  "rate": "1617.300000",
  "networkFeeUsd": "1.130000",
  "serviceFeeUsd": "0.500000",
  "convertedAmount": "200000.00",
  "expiresAt": "2025-03-21T21:05:13.393Z",
  "ycReference": "JJ5275168",
  "sequenceId": "53f7c7fa-f2bb-450c-8f6d-9ff0000f99",
  "createdAt": "2025-03-21T20:55:13.393Z"
}
​
id
string
Unique collection ID (UUID)
​
status
string
Collection status: pending | processing | completed | expired | failed | refunded
​
bankInfo
object
Bank account details where the customer should deposit fiat
​
settlementInfo
object
Crypto settlement details
​
rate
string
Exchange rate (local currency to USD)
​
networkFeeUsd
string
Network fee in USD
​
serviceFeeUsd
string
Service fee in USD
​
convertedAmount
string
Converted fiat amount
​
expiresAt
string
ISO 8601 timestamp when the collection expires
​
ycReference
string
YellowCard reference number
​
sequenceId
string
Unique sequence ID for tracking
You must provide either amount (USD) or localAmount (local currency) — not both. Omitting both will return a 400 error.
After creation, display the bankInfo to the customer so they can deposit fiat. The collection status will update automatically when the deposit is confirmed. Poll Get Collection or Refresh Status to track progress.