Skip to main content
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 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

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

​
Query parameters

​
accountId
string
required
The ID of the account to work with.Allowable values: An existing accountId (≤ 36 characters)

​
Request body schema

​
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
​
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)
​
displayName
string
Display name for the payment.Allowable values: A string [ 1 .. 255 ] characters
​
returnUrl
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://)
​
requesterIpAddress
string
The IP address of the payment requester.
​
expiryMinutes
integer
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. 
{
  "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"
}
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. 
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 '{}'

​
Path parameters

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

​
Query parameters

​
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. 
{
  "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"
}
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.
The list response does not include link or returnUrl for each payment. To retrieve these fields, use GET /stablecoins/payments/{id} with include=link.
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'

​
Query parameters

​
accountId
string
required
The ID of the account to work with.Allowable values: An existing accountId (≤ 36 characters)
​
budgetId
string
The ID of the budget to work with.Allowable values: A valid UUID (≤ 36 characters)
​
limit
integer
required
The maximum number of results to return. For example, limit=200. Defaults to 100 if not provided.Allowable values: [ 1 .. 1000 ]
​
offset
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

​
Response

If your request is successful, you’ll receive a 200 response. 
{
  "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"
    }
  ]
}
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. 
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'

​
Path parameters

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

​
Query parameters

​
accountId
string
required
The ID of the account to work with.Allowable values: An existing accountId (≤ 36 characters)
​
include
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

​
Response

If your request is successful, you’ll receive a 200 response. 
{
  "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"
}
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
  • 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.
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.

​
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.
Error response structure
[
  {
    "path": "string",
    "message": "string",
    "errorCode": "string"
  }
]

​
Common error scenarios

Missing a required field — 400 Bad Request 
[
  {
    "path": "remitterId",
    "message": "Required"
  }
]
Invalid UUID format — 400 Bad Request 
[
  {
    "path": "remitterId",
    "message": "Invalid uuid"
  }
]
Invalid amount (below minimum) — 400 Bad Request 
[
  {
    "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.