Card

Customers can make payments with their credit and debit cards. The API returns a payment link that the customer can use to securely enter their card details and complete the transaction.

To create a card collection, Initiate a collection request with at least one payment method. You can collect funds to either an internal account, internal crypto wallet, or external crypto wallet. For internal destinations, provide the account or wallet ID. For external crypto wallets, provide the wallet address and network:

curl --request POST \
     --url https://api.gravv.xyz/v1/collections \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: order_789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": "50",
  "currency": "USD",
  "country": "NG",
  "customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "client_customer_id": "checkers_user",
  "client_reference": "9d8184a1-4a19-b74d-4797-9896aed01332",
  "source": {
    "source_type": "external",
    "methods": [
      "card"
    ]
  },
  "destination": {
    "id": "bccb74d8-9715-478d-bcac-9d8184a19530",
    "destination_type": "internal_crypto_wallet"
    },
  "metadata": {
    "order_id": "12345",
    "source_platform": "mobile_app"
  }
}
'

You will receive a response similar to this:

{
  "data": {
    "amount": "50",
    "client_reference": "trasdfausdaa",
    "country": "KE",
    "currency": "USD",
    "onramp_status": "initialized",
    "payment_link": "https://pay-staging.gravv.xyz?transaction_id=07b655cc-3dbd-4f6c-a16c-4657946d2e08",
    "raw_payment_link": "https://sandbox.coinflow.cash/polygon/purchase...",
    "transaction_id": "07b655cc-3dbd-4f6c-a16c-4657946d2e08",
    "transaction_status": "pending"
  },
  "error": null
}

Collect to external crypto wallet

To collect funds directly to an external crypto wallet, set destination_type to external_crypto_wallet and provide the wallet address and network:

curl --request POST \
     --url https://api.gravv.xyz/v1/collections \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: order_789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": "50",
  "currency": "USD",
  "country": "NG",
  "customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "client_customer_id": "checkers_user",
  "client_reference": "9d8184a1-4a19-b74d-4797-9896aed01332",
  "source": {
    "source_type": "external",
    "methods": [
      "card"
    ]
  },
  "destination": {
    "destination_type": "external_crypto_wallet",
    "wallet_address": "0x445906a6766927c5da8b2fca0e0db5d7b5565ef8",
    "network": "polygon"
  },
  "metadata": {
    "order_id": "12345"
  }
}
'

Attach custom data with metadata

Use the optional metadata field to attach custom JSON data to collection requests. This data is returned in webhook notifications, allowing you to track additional transaction details:

"metadata": {
  "reference": "12345",
  "description": "card collections"
}