Create an off-ramp or on-ramp quote

Creates a quote for a connector and amount. Omit type (or send any value other than onramp) for an off-ramp quote; send type=onramp for an on-ramp quote.

Off-ramp. amount is the recipient amount in the sending currency (fee-exclusive): the fee is added on top, so total = amount + fee. Exactly one of beneficiaryId or transactionType is required — never both, never neither. beneficiaryId prices the quote for the corridor the payment will actually execute as (type derived server-side from the association and the beneficiary). transactionType (C2C/C2B/B2C/B2B) prices an exploratory quote before a beneficiary is chosen. The returned quoteId is what POST /v1/payments/offramp executes against, and it expires roughly two minutes after creation.

On-ramp. amount is what the paying counterparty pays in, in the collection currency. transactionType is optional and beneficiaryId is not used. In the response, sendAmount and total are both the amount collected, and receiveAmount is what lands in your wallet after fee has been deducted. The returned quoteId is what POST /v1/payments/onramp executes against, before expiresAt.

POST

quotes

Create an off-ramp or on-ramp quote

curl --request POST \
  --url https://api.zeam.money/gw/v1/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "connectorId": "44444444-4444-4444-4444-444444444444",
  "amount": 100,
  "beneficiaryId": "77777777-7777-7777-7777-777777777777"
}
'

{
  "quoteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "connectorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sendAmount": 123,
  "sendCurrency": "<string>",
  "receiveAmount": 123,
  "receiveCurrency": "<string>",
  "rate": 123,
  "fee": 123,
  "feeCurrency": "<string>",
  "total": 123,
  "expiresAt": "<string>"
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Access token issued by POST /v1/auth/token.

x-zeam-auth

string

header

required

Application secret (the apiKey issued at registration), required on every request.

Query Parameters

type

enum<string>

Send onramp for an on-ramp quote. Omit it for an off-ramp quote.

Available options:

onramp

Body

application/json

connectorId

string<uuid>

required

amount

number

required

Recipient amount in the sending currency (fee-exclusive). Must be greater than 0.

beneficiaryId

string<uuid>

Exactly one of beneficiaryId or transactionType is required — never both, never neither. Prices the quote for the corridor the payment will actually execute as: the transaction type is derived server-side from this beneficiary and the caller's association.

transactionType

enum<string>

Exactly one of beneficiaryId or transactionType is required — never both, never neither. Prices an exploratory quote directly for this corridor, before a beneficiary is chosen.

Available options:

C2C,

C2B,

B2C,

B2B

paymentDestinationId

string<uuid>

Optional, with beneficiaryId. The destination the payment will pay; the quote is then attributed to it for off-ramp limits. Pass it whenever you know it — the submit requires the same id.

Response

Quote created.

quoteId

string<uuid>

required

connectorId

string<uuid>

required

sendAmount

number

Amount debited in the sending currency, as confirmed by the connector.

sendCurrency

string

receiveAmount

number

Amount the beneficiary receives.

receiveCurrency

string

rate

number

fee

number

The only fee the user pays. An exact configured BUSINESS/OffRamp fee row wins (including zero); otherwise this is the connector's fee.

feeCurrency

string

total

number

Exactly sendAmount plus fee, as authoritatively priced and snapshotted server-side.

expiresAt

string

ISO 8601 expiry. Quotes expire roughly two minutes after creation.

Create an off-ramp or on-ramp quote

curl --request POST \
  --url https://api.zeam.money/gw/v1/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "connectorId": "44444444-4444-4444-4444-444444444444",
  "amount": 100,
  "beneficiaryId": "77777777-7777-7777-7777-777777777777"
}
'

{
  "quoteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "connectorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sendAmount": 123,
  "sendCurrency": "<string>",
  "receiveAmount": 123,
  "receiveCurrency": "<string>",
  "rate": 123,
  "fee": 123,
  "feeCurrency": "<string>",
  "total": 123,
  "expiresAt": "<string>"
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Overview

Auth

Wallets

Assets

Beneficiaries

Connectors

Quotes

Payments

Transactions

Statements

Webhooks

Create an off-ramp or on-ramp quote

Authorizations

Query Parameters

Body

Response