Skip to main content
If your account holds others beneath it, you can move prepaid credit to and from them over the same API you already send with. No separate portal sign-in and no second credential: the login you send messages with is the one that moves the money.
Available from 0.10.0. Before it, funding an account beneath yours meant signing in to the customer portal by email link — which no billing system of your own could do.

​
The three endpoints

direction has no default and must be one of two words. down funds the named account; up takes credit back from it. A value that is neither is refused rather than assumed — the two move money in opposite directions, and guessing would be the worst possible way to be wrong.

​
Queued, not sent

A 202 does not mean the balances have changed. It means the transfer is recorded and will be applied on the gateway’s next balance poll — normally within a minute.
That is deliberate rather than a limitation. Balances have exactly one writer, and it checks sufficiency in the same statement that moves the money. So whether the paying account can afford a transfer is decided at the moment it is applied, not at the moment you asked — which is the only way to get the right answer when that account is also sending traffic. Ask whether it landed:
There are two statuses, and there is deliberately no refused. A transfer the gateway cannot apply — the payer was short when its turn came, or the receiving account has no balance open — stays pending and keeps trying. It is not discarded, and nothing is half-done: a transfer either moves in full or not at all. If one sits pending far longer than a poll interval, the payer did not have the money at any point since you asked.

​
What it will not let you do

You cannot choose who pays. The paying account is always the one your login bills to. A field in the body naming another account is ignored — there is no request you can construct that spends somebody else’s credit. You cannot name an account you do not hold. Both directions are checked the same way, and a 404 is what you get for an account outside your own — including one that exists and belongs to somebody else. direction: "up" does not relax this; if anything it is the direction that matters more, because a pull takes money away. You cannot move credit without holding accounts at all. If nothing sits beneath your account, every one of these endpoints answers 404.

​
Not sending the same transfer twice

idempotency_key is yours to choose and is required. Send the same one again and you get 409 with the id of the transfer you already made — not a second movement.
Use something from your own system that identifies the intent — an invoice line, a job id, a date and sequence. Two different customers may safely use the same key as each other; keys are scoped to the account that sent them.
Retry on a timeout. If a request times out you do not know whether it landed, and sending it again with the same key is safe: either it queues for the first time, or you get the 409 that tells you it already had — with the id, so you can check it.

​
Amounts

Four decimal places, as a string, with no thousands separators and no currency symbol.

​
What the other account sees

A transfer appears on both accounts’ ledgers, so an account you fund can see where the credit came from, and a movement either of you disputes is checkable by either of you. The same is true of a pull: taking credit back is recorded on the account you took it from.

​
Responses

Balance and quotes

What is left, and what a message will cost.

Authentication

The credentials these endpoints use.