---
title: "Create payment intent"
description: "Creates a card payment intent and returns a payment link for the hosted checkout UI."
protocol: rest
method: POST
endpoint: "/v1/collections/cards/payment-intents"
baseUrl: "https://api.gravv.xyz"
group: "Collections"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Create payment intent

<Endpoint method="POST" path="/v1/collections/cards/payment-intents" />

Creates a card payment intent and returns a payment link for the hosted checkout UI.

_**If you provide a `card_token`, the service automatically initiates a charge after creating the intent.**_

## 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="customer_id" body="customer_id" type="string" required>
</ParamField>

<ParamField name="client_customer_id" body="client_customer_id" type="string" required>
</ParamField>

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

<ParamField name="currency" body="currency" type="string" required>
</ParamField>

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

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

  <Expandable title="properties">
    <ParamField name="destination_type" body="destination.destination_type" type="string" required>

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

    <ParamField name="id" body="destination.id" type="string" required>
      Account ID or wallet ID, depending on destination_type
    </ParamField>

    <ParamField name="wallet_address" body="destination.wallet_address" type="string">
      Required when destination_type is external_crypto_wallet
    </ParamField>

    <ParamField name="network" body="destination.network" type="string">
      Required when destination_type is external_crypto_wallet

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

  </Expandable>
</ParamField>

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

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

      Possible values: `external`
    </ParamField>

    <ParamField name="id" body="source.id" type="string" required>
      Source identifier required by the provider
    </ParamField>

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

      Possible values: `card`
    </ParamField>

  </Expandable>
</ParamField>

<ParamField name="card_token" body="card_token" type="string">
  To auto-charge a customer, use the token you got from the webhook response in your first call of this endpoint.
</ParamField>

<ParamField name="metadata" body="metadata" type="object">
</ParamField>

### Request Examples

<RequestExample>

```json title="CreateIntentOnly"
{
  "customer_id": "f827e428-c497-4b21-8855-99d978909c28",
  "client_customer_id": "merchant-user-123",
  "amount": "3.50",
  "currency": "USD",
  "client_reference": "order-abc-123",
  "destination": {
    "destination_type": "internal_crypto_wallet",
    "id": "b628ff35-429b-48f7-bcf0-6a49df106fc6"
  },
  "source": {
    "source_type": "external",
    "id": "src_80aebb6ea2594a74bc215a64",
    "methods": [
      "card"
    ]
  },
  "metadata": {
    "order_id": "ord_123"
  }
}
```

```json title="CreateIntentAndCharge"
{
  "customer_id": "f827e428-c497-4b21-8855-99d978909c28",
  "amount": "3.50",
  "currency": "USD",
  "destination": {
    "destination_type": "internal_crypto_wallet",
    "id": "b628ff35-429b-48f7-bcf0-6a49df106fc6"
  },
  "source": {
    "source_type": "external",
    "id": "src_80aebb6ea2594a74bc215a64",
    "methods": [
      "card"
    ]
  },
  "card_token": "tokn_80aebb6ea2594a74bc215a64"
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | Payment intent created |
| `400` | Bad request — invalid or missing parameters |

### 200 response


One of the following variants:

<Expandable title="Intent created (no card token)">
  <ResponseField name="intent_id" type="string">
  </ResponseField>

  <ResponseField name="client_secret" type="string">
    AES-256-GCM key material for client-side card encryption
  </ResponseField>

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

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

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

  <ResponseField name="requires_action" type="boolean">
  </ResponseField>

  <ResponseField name="payment_key" type="string">
    Signed JWT for hosted UI operations
  </ResponseField>

  <ResponseField name="payment_link" type="string">
    Ready-to-use URL with an embedded session parameter for the hosted UI
  </ResponseField>

  <ResponseField name="metadata" type="object">
  </ResponseField>

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

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

</Expandable>

<Expandable title="Payment intent for auto-charge using token">
  <ResponseField name="intent_id" type="string">
  </ResponseField>

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

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

    Possible values: `succeeded`
  </ResponseField>

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

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

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

  <ResponseField name="requires_action" type="boolean">
  </ResponseField>

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

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

</Expandable>

<ResponseExample>

```json title="IntentCreated"
{
  "intent_id": "pi_429f578b-675a-4b68-abe3-856cd976257f",
  "client_secret": "pis_a1b2c3d4...",
  "client_reference": "order-abc-123",
  "status": "created",
  "amount": "100.50",
  "currency": "USD",
  "requires_action": false,
  "payment_key": "eyJhbGciOiJIUzI1NiIs...",
  "payment_link": "https://your-hosted-ui.com/pi_429f578b-...?session=eyJqd3Q...",
  "metadata": {
    "order_id": "ord_123"
  },
  "created_at": "2026-04-08T10:00:00Z",
  "expires_at": "2026-04-09T10:00:00Z"
}
```

```json title="AutoChargeSucceeded"
{
  "intent_id": "pi_429f578b-675a-4b68-abe3-856cd976257f",
  "client_secret": "pis_a1b2c3d4...",
  "status": "succeeded",
  "transaction_id": "txn_a1b2c3d4-...",
  "amount": "100.50",
  "currency": "USD",
  "requires_action": false,
  "created_at": "2026-04-08T10:00:00Z",
  "expires_at": "2026-04-09T10:00:00Z"
}
```

</ResponseExample>

### 400 response

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

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

## Authorization

- **ApiKeyAuth**