---
title: "Create a payment link"
description: "Creates a new payment link that can be shared with a payer to collect a crypto payment."
protocol: rest
method: POST
endpoint: "/v1/payment-links"
baseUrl: "https://api.gravv.xyz"
group: "Payment Links"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Create a payment link

<Endpoint method="POST" path="/v1/payment-links" />

Creates a new payment link that can be shared with a payer to collect a crypto payment.

On success, the API returns a shareable `link_url` along with wallet addresses for each network specified in `supported_networks`. The payer visits the link and completes the payment on their preferred network.

## Supported networks

Pass one or more of the following values in `supported_networks`:

- stellar
- ethereum
- polygon
- avalanche
- solana

A wallet address is automatically provisioned for each requested network and returned in the `wallet_addresses` field of the response.

## 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="payer_name" body="payer_name" type="string" required>
  Name of the person who will make the payment.
</ParamField>

<ParamField name="payer_email" body="payer_email" type="string,null">
  Email address of the person who will make the payment.
</ParamField>

<ParamField name="settlement_account_id" body="settlement_account_id" type="string" required>
  ID of the account where settled funds will be deposited after a successful payment.
</ParamField>

<ParamField name="supported_networks" body="supported_networks" type="string[]" required>
  List of blockchain networks to accept payments on. Wallet addresses for each specified network are automatically provisioned and included in the response.

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

<ParamField name="customer_id" body="customer_id" type="string" required>
  ID of the customer this payment link is created for.
</ParamField>

### Request Examples

<RequestExample>

```json title="MultiNetworkLink"
{
  "payer_name": "payer2",
  "payer_email": "payer@example.com",
  "settlement_account_id": "b3e3c9fd-77ed-4d14-9c45-68db60d17d3a",
  "supported_networks": [
    "stellar",
    "ethereum"
  ],
  "customer_id": "5e713759-3416-44f5-b797-efd0299aefc1"
}
```

```json title="SingleNetworkLink"
{
  "payer_name": "John",
  "payer_email": "john@mail.com",
  "settlement_account_id": "872a53c4-9640-4b7a-800d-6875c9af9791",
  "supported_networks": [
    "polygon"
  ],
  "customer_id": "5e713759-3416-44f5-b797-efd0299aefc1"
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | Payment link created successfully. |
| `400` | Invalid request parameters. |
| `404` | Customer or settlement account not found. |

### 200 response

<ResponseField name="data" type="object" required>

  <Expandable title="properties">
    <ResponseField name="id" type="string" required>
      Unique identifier for the payment link.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      Timestamp when the payment link was created (UTC).
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      Timestamp when the payment link was last updated (UTC).
    </ResponseField>

    <ResponseField name="customer_id" type="string" required>
      ID of the customer associated with this payment link.
    </ResponseField>

    <ResponseField name="tenant_id" type="string" required>
      ID of the tenant that owns this payment link.
    </ResponseField>

    <ResponseField name="payer_name" type="string" required>
      Name of the person making the payment.
    </ResponseField>

    <ResponseField name="payer_email" type="string,null">
      Email address of the person making the payment.
    </ResponseField>

    <ResponseField name="payee_name" type="string" required>
      Name of the person or business receiving the payment.
    </ResponseField>

    <ResponseField name="settlement_account_id" type="string" required>
      ID of the account where settled funds will be deposited after a successful payment.
    </ResponseField>

    <ResponseField name="supported_networks" type="string[]" required>
      List of blockchain networks the payer can use to complete the payment.

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

    <ResponseField name="wallet_addresses" type="object" required>
      A map of blockchain network names to their corresponding wallet addresses for receiving crypto payments.
    </ResponseField>

    <ResponseField name="link_url" type="string,null">
      Shareable URL the payer visits to complete the payment.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current status of the payment link.

      Possible values: `active`, `paused`
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="any" required>
  Error information if the request failed.
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": {
    "id": "b905cc64-0f90-4de0-a77c-b183de86b248",
    "created_at": "2026-05-07T15:39:02.639185821Z",
    "updated_at": "2026-05-07T15:39:02.639186702Z",
    "customer_id": "5e713759-3416-44f5-b797-efd0299aefc1",
    "tenant_id": "dfa96ede-fc13-43cf-8328-8b910d1cd1d2",
    "payer_name": "payer2",
    "payer_email": "payer@example.com",
    "payee_name": "Rose",
    "settlement_account_id": "b3e3c9fd-77ed-4d14-9c45-68db60d17d3a",
    "supported_networks": [
      "stellar",
      "ethereum"
    ],
    "wallet_addresses": {
      "ethereum": "0x119827bef8a3030cd401478fa7b33ac94d3c2572",
      "stellar": "GD2WTFAKQJA4BRQRNY3RWGWOFMK52WXZWV3CPCHZV2SJP2QGNBIL6TXQ"
    },
    "link_url": "https://stables.gravv.xyz/b905cc64-0f90-4de0-a77c-b183de86b248",
    "status": "active"
  },
  "error": null
}
```

</ResponseExample>

### 400 response

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

<ResponseField name="error" type="string" required>
  Human-readable error message.
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": "Invalid request parameters"
}
```

</ResponseExample>

### 404 response

<ResponseField name="data" type="any" required>
  Always null for error responses.
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message.
</ResponseField>

<ResponseField name="error" type="any">

  <Expandable title="properties">
    <ResponseField name="code" type="any">
    </ResponseField>

    <ResponseField name="message" type="any">
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Customer not found",
    "details": {}
  }
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**