Skip to main content
POST
/
payments
Creates a payment. This is where most implementations start.
curl --request POST \
  --url https://api.example.com/payments \
  --header 'Content-Type: application/json' \
  --header 'x-digest-key: <x-digest-key>' \
  --header 'x-digest-signature: <x-digest-signature>' \
  --header 'x-digest-timestamp: <x-digest-timestamp>' \
  --data '
{
  "amount": {
    "currency": "USD",
    "value": 1000
  },
  "description": "Payment for order 12345",
  "redirectUrl": "https://example.com/redirect",
  "name": "Example Store",
  "cancelUrl": "https://example.com/cancel",
  "webhookUrl": "https://example.com/webhook",
  "locale": "en",
  "metadata": {
    "orderId": 12345
  },
  "partnerId": "4cfad08e-1b41-4283-b4cc-f916cd4beba0",
  "escrowPayee": "GBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "escrowPlatformFee": 500
}
'
{
  "id": "pt_AEtKAcN9d-",
  "createdAt": "2023-11-18T20:46:15.652Z",
  "updatedAt": "2023-11-18T20:46:15.652Z",
  "expiresAt": "2023-11-18T21:16:15.649Z",
  "mode": "test",
  "amount": {
    "value": 200,
    "currency": "USD"
  },
  "description": "Buying phone",
  "status": "open",
  "settlement_status": "open",
  "redirectUrl": "https://example.com",
  "checkout_id": "pt_AEtKAcN9d-",
  "webhookUrl": "https://example.com/webhook",
  "hostedUrl": "https://ebioro-sandbox-merchant-widget.netlify.app/payments?paymentId=pt_QKTDINJ662&auth_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ0ZXN0LmViaW9yby5jb20iLCJhdWQiOiJodHRwczovL3Rlc3QtZWJpb3JvLW1lcmNoYW50LXNlcnZpY2UtMzgxNTIyNmU5MmE4Lmhlcm9rdWFwcC5jb20iLCJzdWIiOiJjMzMyZTlkYi1kYjQ1LTQ1ZmQtOTFmMy03NGNiNWU5NTQzYzQiLCJpYXQiOjE3MTQwNjcxOTIsImV4cCI6MTcxNDA3MDc5Mn0.EY5xyWptYzD1HgJPUev6LGMRFFZ8HDZOsE2Vk35OASk&lang=es",
  "qrCode": "web+stellar:pay?destination=GAPU7KB2B2USVSWBFJRHGX7AYIWYKF2W44WWDCYEJTEER5D2QYEGD5GM&amount=2.68&asset_code=USDC&asset_issuer=GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5&memo=pt_AEtKAcN9d-&memo_type=text&msg=Buying+phone",
  "merchantName": "Test Store",
  "cancelUrl": "https://example.com/cancel",
  "locale": "es",
  "metadata": {},
  "stellarTxId": "1b680e9577572a0c3e648dcc1686373c87417d9ec17614d0ed5bf0ca397f8fcd",
  "settlement_stellarTxId": "1b680e9577572a0c3e648dcc1686373c87417d9ec17614d0ed5bf0ca397f8fcd",
  "settlement_currency": "USDC",
  "settlement_amount": 2663,
  "settlement_fee": 66.575,
  "amount_paid": 0,
  "history": [
    {
      "time": 1714124827333,
      "status": "success",
      "description": "Payment created"
    }
  ],
  "sender_account": "GDFJ7PTIJGDINCLD7ZWZMYURELPMP6JZ6NMJBDBHKDXBFFWBC4SUFA4F",
  "asset_id": "USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
  "refunded": false,
  "type": "order",
  "partner_id": "4f56c1ff-837c-4a1c-b372-1ddf840f252c"
}

Headers

​
x-digest-timestamp
string
required

Current Unix timestamp

​
x-digest-key
string
required

Your public api key

​
x-digest-signature
string
required

Digest Auth Signature

Body

application/json
​
amount
object
required

The amount to be charged, expressed in the smallest unit of the currency (e.g., cents for USD).

Example:
{ "currency": "USD", "value": 1000 }
​
description
string
required

A description of the payment. This will be displayed to the customer.

Example:

"Payment for order 12345"

​
redirectUrl
string
required

URL to redirect the customer after the payment process.

Example:

"https://example.com/redirect"

​
name
string

The name of your store, shown to the customer during payment. Defaults to the merchant name if not provided.

Example:

"Example Store"

​
cancelUrl
string

URL where the customer is redirected if they cancel the payment. Defaults to redirectUrl if not provided.

Example:

"https://example.com/cancel"

​
webhookUrl
string

Server URL to receive payment status updates via webhook.

Example:

"https://example.com/webhook"

​
locale
string

Locale setting for the payment page, used to preset the language shown to the customer. Supported locales include [en, es].

Example:

"en"

​
metadata
object

Custom metadata to be associated with the payment. This can be any structured data relevant to the payment.

Example:
{ "orderId": 12345 }
​
partnerId
string

For integrations done via an ebioro partner

Example:

"4cfad08e-1b41-4283-b4cc-f916cd4beba0"

​
escrowPayee
string

Stellar address of the fund recipient for escrow payments. Use this when the payee is a different party from the merchant — i.e., the driver in a ride-hailing app (Uber), the host in a rental platform (Airbnb), or the freelancer in a services marketplace (Upwork). If omitted, defaults to the merchant's Stellar account (common for remittances and POS use cases). Only applicable for merchants with settlement_mode = escrow.

Example:

"GBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

​
escrowPlatformFee
integer

Platform fee in basis points (1% = 100 bps) to be deducted from the escrowed amount at release time. If omitted, defaults to the merchant's configured platform fee. Only applicable for merchants with settlement_mode = escrow.

Example:

500

Response

On success the endpoint will return a JSON object with detailed payment information.

​
id
string
​
createdAt
string
​
updatedAt
string
​
expiresAt
string
​
mode
string
​
amount
object
​
description
string
​
status
string
​
settlement_status
string
​
redirectUrl
string
​
checkout_id
string
​
webhookUrl
string
​
hostedUrl
string
​
qrCode
string
​
merchantName
string
​
cancelUrl
string
​
locale
string
​
metadata
object
​
stellarTxId
string
​
settlement_stellarTxId
string
​
settlement_currency
string
​
settlement_amount
number
​
settlement_fee
number
​
amount_paid
number
​
history
object[]
​
sender_account
string
​
asset_id
string
​
refunded
boolean
​
type
string
​
partner_id
string
​
escrow_status
string

Current escrow status. Only present for merchants with settlement_mode = escrow. Possible values: created, funded, failed.

​
escrow_order_id
string

The on-chain escrow order ID. Only present for merchants with settlement_mode = escrow.

​
escrow_contract_address
string

The Soroban escrow contract address. Only present for merchants with settlement_mode = escrow.

​
escrow_platform_fee_bps
integer

Platform fee in basis points (1% = 100 bps) to be deducted at release time. Only present for merchants with settlement_mode = escrow.