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.

  1. The customer is ACTIVE. See Onboarding a customer.
  2. The customer holds fiat_collection and it is APPROVED, on both gates. See Endorsements.
  3. A virtual account exists and virtual_account.activated has 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.

EventWhat it means
deposit.createdMoney arrived and we have a deposit. Nothing is spendable.
deposit.updatedA status moved. Read all four.
deposit.creditedThe 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.

FieldWhat it holds
nameThe payer's name, where the rail record carries it
bank_nameThe payer's bank
account_last4The last four digits of the account they paid from
railThe rail the payment arrived on
rail_referenceThe 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.


Did this page help you?