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.
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 paymenturn:uuid:e7d14b39-8a2c-4f05-b6e1-2c9f7a3d5b18: The id of your customer who is paidurn:uuid:3c9a7e52-41f6-4b8d-a0e2-6d1f9b4c8a27: The id the payer’s institution registered the payer underdid:web:originator.example:pt: The DID of the payer’s institutionDE89370400440532013000: The merchant’s IBAN
{
"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.
| Field | What to send |
|---|---|
amount Required string, decimal | The amount, in whole units of the currency or the asset, such as "129.00". |
currency string, ISO 4217 | The currency you price the payment in, such as USD. To price it in a crypto asset instead, send asset. |
supported_assets Optional array of strings | The assets you accept, as symbols or CAIP-19 identifiers. |
ref Optional string, UUID | Your own reference for the payment. Notabene never creates two payments with the same ref, so you can retry safely. |
merchant_id string | The id of your customer who is paid. |
customer Optional object | The payer, as an id and an optional name. Use the id the payer’s institution registered its customer under. |
customer_entity Optional string, DID | The 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 string | An ISO 20022 purpose code of 1 to 4 uppercase letters or digits, such as SUPP for a supplier payment. |
merchant_account Optional string or object | The account the payment is addressed to, such as an IBAN. An IBAN comes back as payto:/. |
| Field | What to send |
|---|---|
amount (required), string, decimal | The amount, in whole units of the currency or the asset, such as "129.00". |
currency, string, ISO 4217 | The currency you price the payment in, such as USD. To price it in a crypto asset instead, send asset. |
supported_assets (optional), array of strings | The assets you accept, as symbols or CAIP-19 identifiers. |
ref (optional), string, UUID | Your own reference for the payment. Notabene never creates two payments with the same ref, so you can retry safely. |
merchant_id, string | The id of your customer who is paid. |
customer (optional), object | The payer, as an id and an optional name. Use the id the payer’s institution registered its customer under. |
customer_entity (optional), string, DID | The 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), string | An ISO 20022 purpose code of 1 to 4 uppercase letters or digits, such as SUPP for a supplier payment. |
merchant_account (optional), string or object | The 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
- Your policies flag a payment: your team authorizes or rejects it, with
POST /api/v1/payments/{id}/authorizeorPOST /api/v1/payments/{id}/reject. - You no longer want a payment you created: withdraw it with
POST /api/v1/payments/{id}/cancel, before it settles. - You want to see where a payment stands:
GET /api/v1/payments/{id}returns itsstatusand its legs, newest first.
Updated 2 days ago
