References and idempotency

Networks fail, connections drop, and a request can reach Sotirea while its answer never reaches you. For most requests that is harmless: ask again. For a payment it is not, because asking again could pay twice. Sotirea makes every payment safe to retry with an Idempotency-Key.

The Idempotency-Key

Every POST /v1/payments carries an Idempotency-Key header that names the payment, such as your own order or payout id:

POST /v1/payments HTTP/1.1
Idempotency-Key: payout-42
Content-Type: application/json

{"vault_id": 7, "chain_id": "eip155:8453", "to": "0x…", "amount": "25000000", "asset": "0x…", "reference": "payout-42"}

• A key is 1 to 64 letters, digits, dots, dashes, underscores or colons. Without one, or with a malformed one, the request is refused 400 with fields.rule idempotency_key.
• The same key with the same payment answers that payment, 202 again, with its id and created_at unchanged, whatever has happened to it since. Two identical requests arriving together still make one payment. So when you are unsure whether a payment was made, send it again with the same key.
• The same key with a different payment is refused 409, with fields.rule idempotency_key. “The same payment” means the same vault, amount, address, asset, network and reference. Addresses and assets are compared without regard to case.
• The payment’s id is api: followed by your organisation’s id and the key, such as api:12:payout-42, so you can work it out without storing the answer.
• Keys belong to your organisation, shared by all its API keys, and are never reused for another payment. Use ids that are unique across everything that pays out.

A failed payment keeps its key

Because the same key always answers the payment it first made, retrying a payment that failed answers the failed payment again. To try again after fixing the cause, such as topping up the gas pool, send it with a new key.

Your references

A reference is your own id, kept beside Sotirea’s. It is 1 to 128 characters with no spaces, and kept exactly as you give it.

• On a vault, it is unique in your organisation and names the vault: opening a vault with a reference that already has one answers that vault. Use your customer’s id. See vaults and addresses.
• On a payment, it need not be unique. It comes back on the payment, on GET /v1/payments?reference=, and on every payment webhook, so you can match an event to your own records. It is often the same as the Idempotency-Key, but it does not have to be.
• On a deposit, vault_reference is the reference of the vault it arrived in, on the deposit and on its webhooks, so you can credit the right customer at once.