Collect an on-ramp payment

Collects from a registered counterparty’s mobile-money payment destination and pays the proceeds into one of your own wallets, executed asynchronously against a quote from POST /v1/quotes?type=onramp. The roles are the reverse of an off-ramp: senderId is the counterparty who pays (a beneficiary record in your association), paymentDestinationId is the payment destination the collection debits, and walletId is your wallet the payout lands in. Pricing is never accepted from the caller; it is resolved server-side from the quote.

The wallet must be verified (403 otherwise). The counterparty’s classification must match the corridor the quote was priced for, and the fields the connector requires must be present on the counterparty and payment destination; a submission that falls short returns a 422 with field-level detail. notifyEmail and notifyWhatsApp notify your own business, at the email or mobile number on your registered profile. Returns 202.

POST

payments

onramp

Collect an on-ramp payment

curl --request POST \
  --url https://api.zeam.money/gw/v1/payments/onramp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "transactionId": "5f0c6e2a-3436-11e5-bf7f-0002a5d5c51b",
  "walletId": "66666666-6666-6666-6666-666666666666",
  "senderId": "77777777-7777-7777-7777-777777777777",
  "paymentDestinationId": "aaaa1111-2222-3333-4444-555566667777",
  "quoteId": "cccc1111-2222-3333-4444-555566667777",
  "purpose": "FAMILY_SUPPORT"
}
'

{
  "transactionRecordId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "accepted",
  "intentId": "<string>",
  "isIdempotent": true,
  "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>"
    }
  ]
}

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

Body

application/json

transactionId

string<uuid>

required

Your transaction id. Replaying it returns the original result.

walletId

string<uuid>

required

Your own wallet the payout lands in.

senderId

string<uuid>

required

The paying counterparty, a beneficiary registered in your association.

paymentDestinationId

string<uuid>

required

The counterparty's payment destination the collection debits.

quoteId

string<uuid>

required

A quote from POST /v1/quotes?type=onramp.

purpose

string

Purpose of remittance. Discover values via GET /v1/payments/enums.

fromRef

string | null

Optional sender-side transaction reference. When supplied: 1-16 characters, letters, digits, and hyphens only. Omit it or send null for no reference.

Maximum string length: 16

Pattern: ^[A-Za-z0-9-]{1,16}$

toRef

string | null

Optional recipient-side transaction reference. When supplied: 1-16 characters, letters, digits, and hyphens only. Omit it or send null for no reference.

Maximum string length: 16

Pattern: ^[A-Za-z0-9-]{1,16}$

senderSourceOfFunds

string

The counterparty's source of funds, when the connector requires it.

senderIdCountryIsoCode

string

ISO 3166-1 alpha-2 country that issued the counterparty's ID, when the connector requires it.

receiverSourceOfFunds

string

Your source of funds, when the connector requires it.

notifyEmail

boolean

Notify your business by email at the address on your registered profile. Mutually exclusive with notifyWhatsApp.

notifyWhatsApp

boolean

Notify your business by WhatsApp at the mobile number on your registered profile. Mutually exclusive with notifyEmail.

Response

On-ramp accepted for asynchronous processing.

A 202 means the submission was accepted for asynchronous execution, not that it settled. Track completion with the Transactions routes or webhooks.

transactionRecordId

string<uuid>

required

The transaction record id, used with GET /v1/transactions/{transactionId}.

status

string

required

Submission status; not a terminal transaction status.

Example:

"accepted"

intentId

string

Execution intent id, when present.

isIdempotent

boolean

True when this response replays a prior submission with the same transactionId.

message

string

Collect an on-ramp payment

curl --request POST \
  --url https://api.zeam.money/gw/v1/payments/onramp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "transactionId": "5f0c6e2a-3436-11e5-bf7f-0002a5d5c51b",
  "walletId": "66666666-6666-6666-6666-666666666666",
  "senderId": "77777777-7777-7777-7777-777777777777",
  "paymentDestinationId": "aaaa1111-2222-3333-4444-555566667777",
  "quoteId": "cccc1111-2222-3333-4444-555566667777",
  "purpose": "FAMILY_SUPPORT"
}
'

{
  "transactionRecordId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "accepted",
  "intentId": "<string>",
  "isIdempotent": true,
  "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>"
    }
  ]
}

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

Collect an on-ramp payment

Authorizations

Body

Response