Payments API

The Payments API has one call to ask for a payment and two to pay one. Payments explains what a payment is and how it goes from the request to its settlement.

The API is in beta. To take part, contact your Solutions Engineer or [email protected].

Ask to be paid

When you are the merchant’s institution, your backend creates the payment with one call. You need an access token and the merchant registered as your customer first. Authentication and Customers show how to get both.

API reference
curl https://sandbox.notabene.id/api/v1/payments \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "ref": "5d2e8b14-7c3a-4f69-9e01-b8a4c6d2f357",
    "amount": "129.00",
    "currency": "USD",
    "supported_assets": [
      "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"
    ],
    "merchant_id": "urn:uuid:e7d14b39-8a2c-4f05-b6e1-2c9f7a3d5b18",
    "customer": {
      "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27"
    },
    "customer_entity": "did:web:originator.example:pt",
    "purpose": "SUPP",
    "merchant_account": "DE89370400440532013000"
  }'const response = await fetch('https://sandbox.notabene.id/api/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "ref": "5d2e8b14-7c3a-4f69-9e01-b8a4c6d2f357",
    "amount": "129.00",
    "currency": "USD",
    "supported_assets": [
      "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"
    ],
    "merchant_id": "urn:uuid:e7d14b39-8a2c-4f05-b6e1-2c9f7a3d5b18",
    "customer": {
      "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27"
    },
    "customer_entity": "did:web:originator.example:pt",
    "purpose": "SUPP",
    "merchant_account": "DE89370400440532013000"
  }),
});
const answer = response.status === 204 ? null : await response.json();import requests

response = requests.post(
    'https://sandbox.notabene.id/api/v1/payments',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
    json={
      "ref": "5d2e8b14-7c3a-4f69-9e01-b8a4c6d2f357",
      "amount": "129.00",
      "currency": "USD",
      "supported_assets": [
        "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"
      ],
      "merchant_id": "urn:uuid:e7d14b39-8a2c-4f05-b6e1-2c9f7a3d5b18",
      "customer": {
        "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27"
      },
      "customer_entity": "did:web:originator.example:pt",
      "purpose": "SUPP",
      "merchant_account": "DE89370400440532013000"
    },
)
answer = None if response.status_code == 204 else response.json()
What to replace
  • 5d2e8b14-7c3a-4f69-9e01-b8a4c6d2f357: A new UUID of yours for each payment
  • urn:uuid:e7d14b39-8a2c-4f05-b6e1-2c9f7a3d5b18: The id of your customer who is paid
  • urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27: The id the payer’s institution registered the payer under
  • did:web:originator.example:pt: The DID of the payer’s institution
  • DE89370400440532013000: The merchant’s IBAN
Response201
{
  "paymentId": "3f2b7c1e-8a4d-4e6f-9b0a-5c1d2e3f4a5b",
  "status": "Active"
}
curl https://sandbox.notabene.id/api/v1/payments \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "ref": "5d2e8b14-7c3a-4f69-9e01-b8a4c6d2f357",
    "amount": "129.00",
    "currency": "USD",
    "supported_assets": [
      "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"
    ],
    "merchant_id": "urn:uuid:e7d14b39-8a2c-4f05-b6e1-2c9f7a3d5b18",
    "customer": {
      "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27"
    },
    "customer_entity": "did:web:originator.example:pt",
    "purpose": "SUPP",
    "merchant_account": "DE89370400440532013000"
  }'
const response = await fetch('https://sandbox.notabene.id/api/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "ref": "5d2e8b14-7c3a-4f69-9e01-b8a4c6d2f357",
    "amount": "129.00",
    "currency": "USD",
    "supported_assets": [
      "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"
    ],
    "merchant_id": "urn:uuid:e7d14b39-8a2c-4f05-b6e1-2c9f7a3d5b18",
    "customer": {
      "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27"
    },
    "customer_entity": "did:web:originator.example:pt",
    "purpose": "SUPP",
    "merchant_account": "DE89370400440532013000"
  }),
});
const answer = response.status === 204 ? null : await response.json();
import requests

response = requests.post(
    'https://sandbox.notabene.id/api/v1/payments',
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
    json={
      "ref": "5d2e8b14-7c3a-4f69-9e01-b8a4c6d2f357",
      "amount": "129.00",
      "currency": "USD",
      "supported_assets": [
        "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"
      ],
      "merchant_id": "urn:uuid:e7d14b39-8a2c-4f05-b6e1-2c9f7a3d5b18",
      "customer": {
        "id": "urn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27"
      },
      "customer_entity": "did:web:originator.example:pt",
      "purpose": "SUPP",
      "merchant_account": "DE89370400440532013000"
    },
)
answer = None if response.status_code == 204 else response.json()
{
  "paymentId": "3f2b7c1e-8a4d-4e6f-9b0a-5c1d2e3f4a5b",
  "status": "Active"
}

The answer is 201 with the paymentId. Keep it, because every later call takes it and the payer’s institution uses the same one.

FieldWhat to send
amount Required string, decimalThe amount, in whole units of the currency or the asset, such as "129.00".
currency string, ISO 4217The currency you price the payment in, such as USD. To price it in a crypto asset instead, send asset.
supported_assets Optional array of stringsThe assets you accept, as symbols or CAIP-19 identifiers.
ref Optional string, UUIDYour own reference for the payment. Notabene never creates two payments with the same ref, so you can retry safely.
merchant_id stringThe id of your customer who is paid.
customer Optional objectThe payer, as an id and an optional name. Use the id the payer’s institution registered its customer under.
customer_entity Optional string, DIDThe DID of the payer’s institution. Leave it out when you do not know it, and the answer holds a payment_link to send to the payer.
purpose Optional stringAn ISO 20022 purpose code of 1 to 4 uppercase letters or digits, such as SUPP for a supplier payment.
merchant_account Optional string or objectThe account the payment is addressed to, such as an IBAN. An IBAN comes back as payto://iban/DE89370400440532013000.
FieldWhat to send
amount (required), string, decimalThe amount, in whole units of the currency or the asset, such as "129.00".
currency, string, ISO 4217The currency you price the payment in, such as USD. To price it in a crypto asset instead, send asset.
supported_assets (optional), array of stringsThe assets you accept, as symbols or CAIP-19 identifiers.
ref (optional), string, UUIDYour own reference for the payment. Notabene never creates two payments with the same ref, so you can retry safely.
merchant_id, stringThe id of your customer who is paid.
customer (optional), objectThe payer, as an id and an optional name. Use the id the payer’s institution registered its customer under.
customer_entity (optional), string, DIDThe DID of the payer’s institution. Leave it out when you do not know it, and the answer holds a payment_link to send to the payer.
purpose (optional), stringAn ISO 20022 purpose code of 1 to 4 uppercase letters or digits, such as SUPP for a supplier payment.
merchant_account (optional), string or objectThe account the payment is addressed to, such as an IBAN. An IBAN comes back as payto://iban/DE89370400440532013000.

Notabene keeps purpose and merchant_account on the payment and returns them when you read it. It does not send them to the payer’s institution. The API reference lists every field.

Pay a request

When you are the payer’s institution, the payment reaches you under the same id, as an Outgoing payment. Your policies run on it, and it is ReadyToSettle once both institutions have authorized it.

A payment priced in a currency has no asset yet, so name the one you pay with. Send it in settlement_asset with POST /api/v1/payments/{id}/authorize. Until you do, recording the hash answers 400.

Then pay on chain, in one step or through intermediaries, and record the transaction hash with POST /api/v1/payments/{id}/settle. The payment is then Settled for both of you.

If your account requires your customer’s approval, the payment waits as Active until you record the decision with POST /api/v1/payments/{id}/customer-approval. Send approved or denied in decision, and with an approval the asset your customer chose in settlement_asset. Without that requirement, the call answers 400.

Intermediaries

When you pay through an intermediary, such as a liquidity provider or a payment processor, each step is a leg of the payment. Add one with POST /api/v1/payments/{id}/legs, and name the intermediary’s institution, the asset and the amount, as you do for a transfer. A leg is a transfer of its own, so it goes through the same checks and has its own status.

The payment settles once no leg is still open, and recording the hash answers 409 until then. If you cancel or reject the payment, the legs that have not settled are cancelled too.

Other calls


Did this page help you?