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 have them converted to USD.

Typical workflow

Create a remitter for the individual or business sending the payment
Create a payment for that remitter using POST /stablecoins/payments
Accept the payment to lock in the exchange rate using POST /stablecoins/payments/{id}/accept
Share the payment link with your customer
Monitor payment status by polling GET /stablecoins/payments/{id}
Once the status is COMPLETED , funds are available in your budget

Create a new stablecoin inbound payment

Post/stablecoins/payments

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.

Sample requestRequest structure

Copy

Copied

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
  }'

Copy

Copied

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
  }'

Query parameters

Parameter	Description
`accountId` string required	The ID of the account to work with. Allowable values: An existing `accountId` (<= 36 characters)

Request body schema

Parameter	Description
`budgetId` string required	The ID of the budget to work with. Allowable values: A valid UUID (<= 36 characters)
`remitterId` string required	The ID of the remitter associated with the payment. Allowable values: A valid UUID
`amount` number required	The amount to be paid. Allowable values: A number >= 10
`displayName` string optional	Display name for the payment. Allowable values: A string [ 1 .. 255 ] characters
`sourceCurrencyCode` string required	The currency the remitter will send. Allowable values: A string [ 3 .. 4 ] characters (e.g., `USDC`)
`destinationCurrencyCode` string required	The currency that should be received into the budget. Allowable values: A string [ 3 .. 4 ] characters (e.g., `USD`)
`returnUrl` string optional	The URL that the customer will be redirected to if they click the Back button on the link url page. Allowable values: A valid URI (must start with https://)
`requesterIpAddress` string optional	The IP address of the payment requester.
`expiryMinutes` integer optional	The number of minutes after which the payment should expire. Allowable values: An integer [ 1 .. 1000000 ]

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.

Sample responseResponse structure

Copy

Copied

{
  "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"
}

Copy

Copied

{
  "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"
}

For more detailed information about this request and its response, see API reference.

Accept a stablecoin inbound payment

Post/stablecoins/payments/{id}/accept

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.

Sample requestRequest structure

Copy

Copied

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 '{}'

Copy

Copied

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 '{}'

Path parameters

Parameter	Description
`id` string required	The unique ID of the payment. Allowable values: A valid UUID

Query parameters

Parameter	Description
`accountId` string required	The ID of the account to work with. Allowable values: An existing `accountId` (<= 36 characters)

Request body schema

Empty object {}

Response

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

Sample responseResponse structure

Copy

Copied

{
  "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"
}

Copy

Copied

{
  "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"
}

For more detailed information about this request and its response, see API reference.

List stablecoin inbound payments

Get/stablecoins/payments

Request

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

Sample requestRequest structure

Copy

Copied

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'

Copy

Copied

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'

Query parameters

Parameter	Description
`accountId` string required	The ID of the account to work with. Allowable values: An existing `accountId` (<= 36 characters)
`budgetId` string optional	The ID of the budget to work with. Allowable values: A valid UUID (<= 36 characters)
`limit` integer optional	The maximum number of results to return. For example, `limit=200`. By default, this is set to `100`. Allowable values: `[ 1 .. 1000 ]`
`offset` integer optional	The number of items to skip before returning results. For example, `offset=100`. By default, this is set to `0`. Allowable values: A valid integer

Response

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

Sample responseResponse structure

Copy

Copied

{
  "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": "2025-01-30T09:00:00Z",
      "updatedAt": "2025-01-30T09:00:00Z"
    }
  ]
}

Copy

Copied

{
  "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"
    }
  ]
}

For more detailed information about this request and its response, see API reference.

Retrieve a specific stablecoin inbound payment

Get/stablecoins/payments/{id}

Request

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

Sample requestRequest structure

Copy

Copied

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'

Copy

Copied

curl -i -X GET \
  'https://api.equalsmoney.com/stablecoins/payments/{id}?accountId=F50091&include=link' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Path parameters

Parameter	Description
`id` string required	The unique ID of the payment. Allowable values: A valid UUID

Query parameters

Parameter	Description
`accountId` string required	The ID of the account to work with. Allowable values: An existing `accountId` (<= 36 characters)
`include` string optional	Controls which optional properties should be attached to the response. Use `include=link` to return the blockchain 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`

Response

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

Sample responseResponse structure

Copy

Copied

{
  "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"
}

Copy

Copied

{
  "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"
}

For more detailed information about this request and its response, see API reference.

Payment statuses

Stablecoin inbound payments can have the following statuses:

PENDING - Payment has been created but not yet detected on the blockchain
DETECTED - Payment has been detected on the blockchain and is being processed
COMPLETED - Payment has been successfully processed and funds have been credited to the budget
FAILED - Payment processing failed
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.
FAILED — If a payment fails during processing, the status changes to FAILED . 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. If the hour elapses before the remitter sends USDC, the payment may expire depending on your expiryMinutes setting.

info

To monitor payment status, poll GET /stablecoins/payments/{id} at regular intervals. Check the status field for changes from PENDING to DETECTED, COMPLETED, FAILED, or EXPIRED.