> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage stablecoin inbound payments

> Create, accept, view, and manage stablecoin inbound payments for your budgets. These endpoints allow you to receive USDC payments from remitters and c

Create, accept, view, and manage stablecoin inbound payments for your budgets. These endpoints allow you to receive USDC payments from remitters and have them converted to USD.

## Typical workflow

1. [Create a remitter](/pages/payments/manage-stablecoin-remitters) for the individual or business sending the payment
2. Create a payment for that remitter using `POST /stablecoins/payments`
3. Accept the payment to lock in the exchange rate using `POST /stablecoins/payments/{id}/accept`
4. Share the payment link with your customer
5. Monitor payment status by polling `GET /stablecoins/payments/{id}`
6. Once the status is `COMPLETE`, funds are available in your budget

## Create a new stablecoin inbound payment

<Note>
  **POST** `/stablecoins/payments`
</Note>

### Request

Use this endpoint to create a new stablecoin inbound payment for a given remitter. The exchange rate isn't locked in until the payment is accepted.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/stablecoins/payments?accountId=F50091' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "budgetId": "775596ae-2624-40af-a9dc-9756110a4a03",
      "remitterId": "a1111111-2222-3333-4444-555555555555",
      "amount": 100,
      "displayName": "Invoice #12345",
      "sourceCurrencyCode": "USDC",
      "destinationCurrencyCode": "USD",
      "returnUrl": "https://www.example.com/receive-money",
      "requesterIpAddress": "127.0.0.1",
      "expiryMinutes": 15
    }'
  ```

  ```bash Request structure theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/stablecoins/payments?accountId=F50091' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "budgetId": "string",
      "remitterId": "string",
      "amount": number,
      "displayName": "string",
      "sourceCurrencyCode": "string",
      "destinationCurrencyCode": "string",
      "returnUrl": "string",
      "requesterIpAddress": "string",
      "expiryMinutes": number
    }'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account to work with.

  Allowable values: An existing `accountId` (≤ 36 characters)
</ParamField>

#### Request body schema

<ParamField body="budgetId" type="string" required>
  The ID of the budget to work with.

  Allowable values: A valid UUID (≤ 36 characters)
</ParamField>

<ParamField body="remitterId" type="string" required>
  The ID of the remitter associated with the payment.

  Allowable values: A valid UUID
</ParamField>

<ParamField body="amount" type="number" required>
  The amount to be paid.

  Allowable values: A number >= 10
</ParamField>

<ParamField body="sourceCurrencyCode" type="string" required>
  The currency the remitter will send.

  Allowable values: A string \[ 3 .. 4 ] characters (e.g., `USDC`)
</ParamField>

<ParamField body="destinationCurrencyCode" type="string" required>
  The currency that should be received into the budget.

  Allowable values: A string \[ 3 .. 4 ] characters (e.g., `USD`)
</ParamField>

<ParamField body="displayName" type="string">
  Display name for the payment.

  Allowable values: A string \[ 1 .. 255 ] characters
</ParamField>

<ParamField body="returnUrl" type="string">
  The URL that your customer will be redirected to if they click the Back button on the hosted payment page. This is not a post-payment redirect — it only applies to the Back button.

  Allowable values: A valid URI (must start with `https://`)
</ParamField>

<ParamField body="requesterIpAddress" type="string">
  The IP address of the payment requester.
</ParamField>

<ParamField body="expiryMinutes" type="integer">
  The number of minutes after which the payment should expire.

  Allowable values: An integer \[ 1 .. 1000000 ]
</ParamField>

### Response

If your request is successful, you'll receive a `201` response. The response includes a `link` object — `link.url` is a hosted payment page where your customer can select a blockchain network and send USDC. The `link.chains` array lists the wallet addresses for direct transfers.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "id": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
    "accountId": "F50091",
    "budgetId": "775596ae-2624-40af-a9dc-9756110a4a03",
    "status": "PENDING",
    "remitterId": "a1111111-2222-3333-4444-555555555555",
    "amount": 100,
    "displayName": "Invoice #12345",
    "sourceCurrencyCode": "USDC",
    "destinationCurrencyCode": "USD",
    "returnUrl": "https://www.example.com/receive-money",
    "link": {
      "url": "https://pay.sandbox.example.com/channel?uuid=9d1f67f2-a647-404b-9b02-247c77be81d0",
      "chains": [
        {
          "protocol": "ETH",
          "address": "0x0000000000000000000000000000000000000000"
        }
      ]
    },
    "expiresAt": "2025-01-30T10:00:00.000Z",
    "createdBy": "John Smith",
    "createdAt": "2025-01-30T09:00:00Z",
    "updatedAt": "2025-01-30T09:00:00Z"
  }
  ```

  ```json Response structure theme={null}
  {
    "id": "string",
    "accountId": "string",
    "budgetId": "string",
    "status": "string",
    "remitterId": "string",
    "amount": number,
    "displayName": "string",
    "sourceCurrencyCode": "string",
    "destinationCurrencyCode": "string",
    "returnUrl": "string",
    "link": {
      "url": "string",
      "chains": [
        {
          "protocol": "string",
          "address": "string"
        }
      ]
    },
    "expiresAt": "string",
    "createdBy": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see API reference](/api-reference/payments/create-a-new-stablecoin-inbound-payment).

## Accept a stablecoin inbound payment

<Note>
  **POST** `/stablecoins/payments/{id}/accept`
</Note>

### Request

Use this endpoint to accept a stablecoin inbound payment. Accepting a payment locks in the stablecoin to fiat exchange rate for one hour. This two-step process (create, then accept) lets you review the payment details before committing to the exchange rate.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/stablecoins/payments/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/accept?accountId=F50091' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```

  ```bash Request structure theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/stablecoins/payments/{id}/accept?accountId=F50091' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{}'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="id" type="string" required>
  The unique ID of the payment.

  Allowable values: A valid UUID
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account to work with.

  Allowable values: An existing `accountId` (≤ 36 characters)
</ParamField>

#### Request body schema

Empty object `{}`

### Response

If your request is successful, you'll receive a `200` response.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "id": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
    "accountId": "F50091",
    "budgetId": "775596ae-2624-40af-a9dc-9756110a4a03",
    "status": "PENDING",
    "remitterId": "a1111111-2222-3333-4444-555555555555",
    "amount": 100,
    "displayName": "Invoice #12345",
    "sourceCurrencyCode": "USDC",
    "destinationCurrencyCode": "USD",
    "returnUrl": "https://www.example.com/receive-money",
    "link": {
      "url": "https://pay.sandbox.example.com/channel?uuid=9d1f67f2-a647-404b-9b02-247c77be81d0",
      "chains": [
        {
        "protocol": "ETH",
        "address": "0x0000000000000000000000000000000000000000"
        }
      ]
    },
    "expiresAt": "2025-01-30T10:00:00.000Z",
    "createdBy": "John Smith",
    "createdAt": "2025-01-30T09:00:00Z",
    "updatedAt": "2025-01-30T09:00:00Z"
  }
  ```

  ```json Response structure theme={null}
  {
    "id": "string",
    "accountId": "string",
    "budgetId": "string",
    "status": "string",
    "remitterId": "string",
    "amount": number,
    "displayName": "string",
    "sourceCurrencyCode": "string",
    "destinationCurrencyCode": "string",
    "returnUrl": "string",
    "link": {
      "url": "string",
      "chains": [
        {
          "protocol": "string",
          "address": "string"
        }
      ]
    },
    "expiresAt": "string",
    "createdBy": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see API reference](/api-reference/payments/accepts-a-stablecoin-inbound-payment).

## List stablecoin inbound payments

<Note>
  **GET** `/stablecoins/payments`
</Note>

### Request

Use this endpoint to retrieve a paginated list of all stablecoin inbound payments for a given budget.

<Info>
  The list response does not include `link` or `returnUrl` for each payment. To retrieve these fields, use `GET /stablecoins/payments/{id}` with `include=link`.
</Info>

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/stablecoins/payments?accountId=F50091&budgetId=775596ae-2624-40af-a9dc-9756110a4a03&limit=200&offset=100' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/stablecoins/payments?accountId={accountId}&budgetId={budgetId}&limit={limit}&offset={offset}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account to work with.

  Allowable values: An existing `accountId` (≤ 36 characters)
</ParamField>

<ParamField body="budgetId" type="string">
  The ID of the budget to work with.

  Allowable values: A valid UUID (≤ 36 characters)
</ParamField>

<ParamField body="limit" type="integer" required>
  The maximum number of results to return. For example, `limit=200`. Defaults to `100` if not provided.

  Allowable values: `[ 1 .. 1000 ]`
</ParamField>

<ParamField body="offset" type="integer" required>
  The number of items to skip before returning results. For example, `offset=100`. Defaults to `0` if not provided.

  Allowable values: A valid integer
</ParamField>

### Response

If your request is successful, you'll receive a `200` response.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "limit": 200,
    "offset": 100,
    "count": 67,
    "rows": [
      {
        "id": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
        "accountId": "F50091",
        "budgetId": "775596ae-2624-40af-a9dc-9756110a4a03",
        "status": "PENDING",
        "remitterId": "a1111111-2222-3333-4444-555555555555",
        "amount": 100,
        "displayName": "Invoice #12345",
        "sourceCurrencyCode": "USDC",
        "destinationCurrencyCode": "USD",
        "expiresAt": "2025-01-30T10:00:00.000Z",
        "createdBy": "John Smith",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z"
      }
    ]
  }
  ```

  ```json Response structure theme={null}
  {
    "limit": number,
    "offset": number,
    "count": number,
    "rows": [
      {
        "id": "string",
        "accountId": "string",
        "budgetId": "string",
        "status": "string",
        "remitterId": "string",
        "amount": number,
        "displayName": "string",
        "sourceCurrencyCode": "string",
        "destinationCurrencyCode": "string",
        "expiresAt": "string",
        "createdBy": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see API reference](/api-reference/payments/list-stablecoin-inbound-payments).

## Retrieve a specific stablecoin inbound payment

<Note>
  **GET** `/stablecoins/payments/{id}`
</Note>

### Request

Use this endpoint to retrieve details of a specific stablecoin inbound payment.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/stablecoins/payments/e9293471-5eb3-4dbc-916c-dbaf9e2deefd?accountId=F50091&include=link' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    '{{https://api.equalsmoney.com/stablecoins/payments/{id}}}?accountId=F50091&include=string' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="id" type="string" required>
  The unique ID of the payment.

  Allowable values: A valid UUID
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account to work with.

  Allowable values: An existing `accountId` (≤ 36 characters)
</ParamField>

<ParamField body="include" type="string">
  Controls which optional properties should be attached to the response. Use `include=link` to return the payment link and chain addresses in the response. This is useful when you need to share the payment link with your customer after the initial creation.

  Allowable values: `link`
</ParamField>

### Response

If your request is successful, you'll receive a `200` response.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "id": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
    "accountId": "F50091",
    "budgetId": "775596ae-2624-40af-a9dc-9756110a4a03",
    "status": "PENDING",
    "remitterId": "a1111111-2222-3333-4444-555555555555",
    "amount": 100,
    "displayName": "Invoice #12345",
    "sourceCurrencyCode": "USDC",
    "destinationCurrencyCode": "USD",
    "returnUrl": "https://www.example.com/receive-money",
    "link": {
      "url": "https://pay.sandbox.example.com/channel?uuid=9d1f67f2-a647-404b-9b02-247c77be81d0",
      "chains": [
        {
          "protocol": "ETH",
          "address": "0x0000000000000000000000000000000000000000"
        }
      ]
    },
    "expiresAt": "2025-01-30T10:00:00.000Z",
    "createdBy": "John Smith",
    "createdAt": "2025-01-30T09:00:00Z",
    "updatedAt": "2025-01-30T09:00:00Z"
  }
  ```

  ```json Response structure theme={null}
  {
    "id": "string",
    "accountId": "string",
    "budgetId": "string",
    "status": "string",
    "remitterId": "string",
    "amount": number,
    "displayName": "string",
    "sourceCurrencyCode": "string",
    "destinationCurrencyCode": "string",
    "returnUrl": "string",
    "link": {
      "url": "string",
      "chains": [
        {
          "protocol": "string",
          "address": "string"
        }
      ]
    },
    "expiresAt": "string",
    "createdBy": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see API reference](/api-reference/payments/retrieve-a-stablecoin-inbound-payment).

## Payment statuses

Stablecoin inbound payments can have the following statuses:

* **PENDING** — Payment has been created but not yet detected on the blockchain
* **PROCESSING** — Payment has been detected on the blockchain and is being processed
* **COMPLETE** — Payment has been successfully processed and funds have been credited to the budget
* **CANCELLED** — Payment processing was cancelled
* **EXPIRED** — Payment was not completed before the expiry time

## Handling payment expiry and failure

* **EXPIRED** — If the remitter doesn't complete the blockchain transfer before the payment expires, the status changes to `EXPIRED`. You'll need to create a new payment and accept it again to generate a fresh exchange rate and payment link.
* **CANCELLED** — If a payment is cancelled during processing, the status changes to `CANCELLED`. Contact your account manager if this occurs repeatedly.
* **Exchange rate expiry** — The exchange rate is locked for one hour from when you accept the payment. The `expiryMinutes` timer runs independently — it starts when the payment is created, not when it's accepted. If `expiryMinutes` is shorter than the time between creation and the remitter's transfer, the payment will expire regardless of the exchange rate lock. If `expiryMinutes` is longer than one hour, the exchange rate lock may lapse before the payment itself expires.

<Info>
  To monitor payment status, poll `GET /stablecoins/payments/{id}` at regular intervals — we recommend every **10–30 seconds**. Check the `status` field for changes from `PENDING` to `PROCESSING`, `COMPLETE`, `CANCELLED`, or `EXPIRED`.
</Info>

## Error responses

If a request fails, the API returns an appropriate HTTP status code along with a JSON array describing the error. Each error object contains a `path` indicating which parameter caused the issue, a `message` explaining the problem, and an optional `errorCode`.

```json Error response structure theme={null}
[
  {
    "path": "string",
    "message": "string",
    "errorCode": "string"
  }
]
```

### Common error scenarios

**Missing a required field** — `400 Bad Request`

```json theme={null}
[
  {
    "path": "remitterId",
    "message": "Required"
  }
]
```

**Invalid UUID format** — `400 Bad Request`

```json theme={null}
[
  {
    "path": "remitterId",
    "message": "Invalid uuid"
  }
]
```

**Invalid amount (below minimum)** — `400 Bad Request`

```json theme={null}
[
  {
    "path": "amount",
    "message": "Number must be greater than or equal to 10"
  }
]
```

**Resource not found** — `403 Forbidden`

If the payment ID or account ID doesn't match an existing resource, the API returns a `403` response.