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 convert them to fiat currency.

Overview

The stablecoin inbound payment workflow follows these steps:

Create a payment - Generate a new payment request for a remitter
Accept the payment - Lock in the exchange rate (valid for 1 hour)
Monitor payment status - List or retrieve payment details
Complete the payment - The remitter sends USDC via the blockchain

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: 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: 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 BVNK 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.

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.bvnk.com/channl?uuid=9d1f67f2-a647-404b-9b02-247c77be81d0",
    "chains": [
      {
        "protocol": "ETH",
        "address": "0x0000000000000000000000000000000000000000"
      }
    ]
  },
  "expiresAt": "2025-01-30T08:30:00.000Z",
  "createdBy": "John Smith",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

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.

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: 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: 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.bvnk.com/channel?uuid=9d1f67f2-a647-404b-9b02-247c77be81d0",
    "chains": [
      {
      "protocol": "ETH",
      "address": "0x0000000000000000000000000000000000000000"
      }
    ]
  },
  "expiresAt": "2025-01-30T08:30:00.000Z",
  "createdBy": "John Smith",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

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=string&limit=200&offset=100' \
  -H 'Authorization: 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: 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-30T08:30:00.000Z",
      "createdBy": "John Smith",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}

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: YOUR_API_KEY_HERE'

Copy

Copied

curl -i -X GET \
  '{{https://api.equalsmoney.com/stablecoins/payments/{id}}}?accountId=F50091&include=string' \
  -H 'Authorization: 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. 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.bvnk.com/channel?uuid=9d1f67f2-a647-404b-9b02-247c77be81d0",
    "chains": [
      {
        "protocol": "ETH",
        "address": "0x0000000000000000000000000000000000000000"
      }
    ]
  },
  "expiresAt": "2025-01-30T08:30:00.000Z",
  "createdBy": "John Smith",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

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

Typical workflow

Create a remitter (see Manage stablecoin remitters documentation)
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 using GET /stablecoins/payments/{id} or webhook notifications
Once status is COMPLETED, funds are available in your budget