Collecting into a Balance
The order of calls for taking local currency into a customer's balance.
This is a common flow. It covers the order to make the calls in, and each step links to the documentation that explains it in more detail.
Before you start
Three things have to be true, and they are three separate waits rather than one.
- The customer is
ACTIVE. See Onboarding a customer. - The customer holds
fiat_collectionand it isAPPROVED, on both gates. See Endorsements. - A virtual account exists and
virtual_account.activatedhas fired. See Virtual accounts and deposit addresses.
Check the route is LIVE before any of this, because a country and currency that is not live is refused at registration rather than at deposit. See Countries and routes.
Choose the account purpose deliberately. BALANCE holds the money as a local stablecoin. CONVERSION converts every deposit that ever lands there. The value is fixed at generation, so a wrong choice means a new instrument.
The sequence
1. Give the payer the instructions.
They send over the local rail.
2. Wait. In order, and each one means something different.
| Event | What it means |
|---|---|
deposit.created | Money arrived and we have a deposit. Nothing is spendable. |
deposit.updated | A status moved. Read all four. |
deposit.credited | The balance moved. Now it is spendable. |
3. Read the balance.
GET /v1/customers/{customerId}/balances
Check the figure landed in available. A total that includes held or reserved money will mislead you. See Balances.
What you learn about the payer
You do not register a payer and there is nothing to submit about them in advance. What the rail tells us arrives on the deposit, in sender, after the money does.
| Field | What it holds |
|---|---|
name | The payer's name, where the rail record carries it |
bank_name | The payer's bank |
account_last4 | The last four digits of the account they paid from |
rail | The rail the payment arrived on |
rail_reference | The rail's own tracking reference |
How much of this is populated depends on the rail. Each market's record carries different fields, so treat sender.name as present where the rail supplies it rather than as guaranteed. rail_reference is the one your customer, their payer and their bank can all see, so it is worth storing.
The payer's tax ID isn't on sender. The rail records carry it in Mexico (RFC or CURP) and Argentina (CUIT), but the API has no field for it today. Don't build a flow that depends on reading it.
Match on more than the amount. Use amount and timestamp, with sender as supporting evidence. Two invoices for the same figure on the same day will reconcile to the wrong one if you match on amount alone.
match on the deposit records how we attributed it, including match_method and candidate_count. It is persisted at decision time and never recomputed, so it is the audit trail for why this money went to this customer.
The mistake to avoid
An arrival is not a credit. deposit.created says money arrived. It does not say the funds settled, and it does not credit anything.
If you release goods, mark an invoice paid, or trigger a payout before deposit.credited, you are acting on money that has not landed. Alfred still has to validate the payer against the rail record, and the balance is credited only once that validation is approved. Wait for deposit.credited.
In sandbox
Nothing is provisioned and you cannot transfer funds in, so you simulate the deposit.
POST /v1/test/customers/{customerId}/deposits/simulate
It runs the same pipeline a real deposit runs, so the events above arrive in the same order. See Testing in sandbox.
What comes next
The balance is the customer's. Converting it or paying it out are separate transactions with their own lifecycles, and this one completing starts neither of them. If a conversion and a payout belong to one commercial flow, pass the same payment_flow_id to each.
Updated 11 days ago

