Register an on-ramp reference

Issues a provider reference (for example an EasyPay number) for one of your customers on a bespoke connector, bound to one of your own wallets.

404: the settlement account is not one of your wallets (including a malformed key), the connector is unknown, or the provider requires the customer to be registered first and they are not.
409: the customer already has references on the connector (list them instead), or the provider’s references could not be assigned.
422: the wallet has no trustline for the connector’s settlement asset, or the connector does not issue references.

POST

onramp

references

curl --request POST \
  --url https://api.zeam.money/gw/v1/onramp/references \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "connectorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "settlementAccount": "<string>",
  "customerId": "<string>"
}
'

{
  "reference": "9505612345678901",
  "routeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": {},
  "relatedReferences": [
    {
      "reference": "<string>",
      "metadata": {}
    }
  ]
}

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

connectorId

string<uuid>

required

settlementAccount

string

required

One of your own wallets' Stellar public keys. The wallet needs a trustline for the connector's settlement asset (422 otherwise).

Pattern: ^G[A-Z2-7]{55}$

customerId

string

required

Your own id for the customer.

Response

The new reference.

reference

string

required

The provider's reference, for example the EasyPay number the customer pays against.

Example:

"9505612345678901"

routeId

string<uuid>

required

The connector id.

metadata

object | null

Provider-specific payment instructions, for example the bank details a Noah customer pays to. Null on a rebind.

Show child attributes

Further references the provider issued for the same customer; null or empty when there are none.

Show child attributes

curl --request POST \
  --url https://api.zeam.money/gw/v1/onramp/references \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "connectorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "settlementAccount": "<string>",
  "customerId": "<string>"
}
'

{
  "reference": "9505612345678901",
  "routeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": {},
  "relatedReferences": [
    {
      "reference": "<string>",
      "metadata": {}
    }
  ]
}

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

Onramp references

Transactions

Statements

Webhooks

Register an on-ramp reference

Authorizations

Body

Response