---
title: "Initiate a collection"
description: "Initiates a collection request using a specified collection method (card, bank transfer, and mobile money)."
protocol: rest
method: POST
endpoint: "/v1/collections"
baseUrl: "https://api.gravv.xyz"
group: "Collections"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Initiate a collection

<Endpoint method="POST" path="/v1/collections" />

Initiates a collection request using a specified collection method (card, bank transfer, and mobile money).

If the collection method is card, a payment link will be generated for the customer to complete the payment. For mobile money and bank transfer methods, payment instructions will be provided.

## Headers

<ParamField name="Idempotency-Key" header="Idempotency-Key" type="string" required>
  Required for POST requests. Reuse only for an identical retry.
</ParamField>

## Request Body

<ParamField name="amount" body="amount" type="string" required>
  Amount to collect
</ParamField>

<ParamField name="currency" body="currency" type="string" required>
  Three-letter uppercase ISO 4217 currency code
</ParamField>

<ParamField name="country" body="country" type="string" required>
  Alpha-2 country code
</ParamField>

<ParamField name="customer_id" body="customer_id" type="string" required>
  Unique customer identifier
</ParamField>

<ParamField name="client_customer_id" body="client_customer_id" type="string" required>
  A unique identifier assigned by the client to reference the customer when storing payment details
</ParamField>

<ParamField name="client_reference" body="client_reference" type="string" required>
  Client unique reference
</ParamField>

<ParamField name="metadata" body="metadata" type="object">
  Custom JSON data that will be returned in webhook notifications for this transaction
</ParamField>

<ParamField name="source" body="source" type="oneOf" required>

  One of the following variants:

  <Expandable title="Card">
    <ParamField name="source_type" body="source.source_type" type="string" required>

      Possible values: `external`
    </ParamField>

    <ParamField name="methods" body="source.methods" type="string[]" required>

      Possible values: `card`, `apple_pay`, `google_pay`, `pix`, `mobile_money`, `bank_transfer`
    </ParamField>

  </Expandable>
</ParamField>

<ParamField name="destination" body="destination" type="oneOf" required>

  One of the following variants:

  <Expandable title="Internal destination">
    <ParamField name="destination_type" body="destination.destination_type" type="string" required>
      Type of internal destination

      Possible values: `internal_account`, `internal_crypto_wallet`
    </ParamField>

    <ParamField name="id" body="destination.id" type="string" required>
      Provide an account ID if destination_type is internal_account, or a wallet ID if destination_type is internal_crypto_wallet
    </ParamField>

  </Expandable>

  <Expandable title="External crypto wallet">
    <ParamField name="destination_type" body="destination.destination_type" type="string" required>

      Possible values: `external_crypto_wallet`
    </ParamField>

    <ParamField name="wallet_address" body="destination.wallet_address" type="string" required>
      Wallet address for the external crypto wallet
    </ParamField>

    <ParamField name="network" body="destination.network" type="string" required>
      Blockchain network for the crypto wallet

      Possible values: `polygon`, `stellar`, `ethereum`, `solana`, `avalanche`
    </ParamField>

  </Expandable>
</ParamField>

### Request Examples

<RequestExample>

```json title="CardCollection"
{
  "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": {
    "something": "i can share"
  }
}
```

```json title="ExternalCryptoWallet"
{
  "source": {
    "source_type": "external",
    "methods": [
      "card"
    ]
  },
  "destination": {
    "destination_type": "external_crypto_wallet",
    "wallet_address": "0x445906a6766927c5da8b2fca0e0db5d7b5565ef8",
    "network": "polygon"
  },
  "amount": "2",
  "currency": "USD",
  "country": "NG",
  "customer_id": "3eb41f1e-0b09-41d0-a1cc-3a60f57a3c5f",
  "client_customer_id": "3eb41f1e-0b09-41d0-a1cc-3a60f57a3c59",
  "client_reference": "657678888S",
  "metadata": {
    "order_id": "12345",
    "source_platform": "mobile_app"
  }
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | Collection initialized successfully |
| `400` | Bad request — invalid or missing parameters |

### 200 response


One of the following variants:

<Expandable title="Card Collection Response">
  <ResponseField name="data" type="object">

    <Expandable title="properties">
      <ResponseField name="amount" type="string">
      </ResponseField>

      <ResponseField name="client_reference" type="string">
      </ResponseField>

      <ResponseField name="country" type="string">
      </ResponseField>

      <ResponseField name="currency" type="string">
      </ResponseField>

      <ResponseField name="onramp_status" type="string">
      </ResponseField>

      <ResponseField name="payment_link" type="string">
        Hosted payment link for card checkout
      </ResponseField>

      <ResponseField name="raw_payment_link" type="string">
      </ResponseField>

      <ResponseField name="transaction_id" type="string">
      </ResponseField>

      <ResponseField name="status" type="string">

        Possible values: `created`, `initialized`, `pending`, `provider_initiated`, `provider_success`, `provider_failed`, `transfer_queued`, `transfer_initiated`, `transfer_success`, `transfer_failed`, `abandoned`, `completed`, `expired`, `refunded`, `cancelled`
      </ResponseField>

    </Expandable>
  </ResponseField>

  <ResponseField name="error" type="null">
  </ResponseField>

</Expandable>

<Expandable title="Mobile Money / Bank Transfer Response">
  <ResponseField name="instruction" type="string">
    HTML instructions for completing the payment
  </ResponseField>

  <ResponseField name="client_reference" type="string">
  </ResponseField>

  <ResponseField name="transaction_id" type="string">
  </ResponseField>

  <ResponseField name="status" type="string">

    Possible values: `created`, `initialized`, `pending`, `provider_initiated`, `provider_success`, `provider_failed`, `transfer_queued`, `transfer_initiated`, `transfer_success`, `transfer_failed`, `abandoned`, `completed`, `expired`, `refunded`, `cancelled`
  </ResponseField>

  <ResponseField name="onramp_status" type="string">
  </ResponseField>

  <ResponseField name="amount" type="string">
  </ResponseField>

  <ResponseField name="currency" type="string">
  </ResponseField>

  <ResponseField name="country" type="string">
  </ResponseField>

</Expandable>

<ResponseExample>

```json title="CardResponse"
{
  "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://provider.example/checkout/polygon/purchase...",
    "transaction_id": "07b655cc-3dbd-4f6c-a16c-4657946d2e08",
    "status": "created"
  },
  "error": null
}
```

```json title="MobileMoneyResponse"
{
  "instruction": "<p>Dear Sam Katana,</p> ... <p>Customer Service</p>",
  "client_reference": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "transaction_id": "e07aa829-cda4-4c51-bd43-09a2f1e6604d",
  "status": "created",
  "onramp_status": "initialized",
  "amount": "50",
  "currency": "ETB",
  "country": "ET"
}
```

```json title="BankTransferResponse"
{
  "instruction": "<p>You have a Pending Payment...</p>",
  "client_reference": "04dfb2e5-1274-4214-b5fd-3415fde7dc17",
  "transaction_id": "e07aa829-cda4-4c51-bd43-09a2f1e6604d",
  "status": "created",
  "onramp_status": "initialized",
  "amount": "50",
  "currency": "ETB",
  "country": "ET"
}
```

</ResponseExample>

### 400 response

<ResponseField name="data" type="null">
</ResponseField>

<ResponseField name="error" type="string">
</ResponseField>

## Authorization

- **ApiKeyAuth**