Connecting the Pieces

What this guide covers

If you’ve read the quickstart but aren’t sure exactly which ID goes where, or why you need to create three different things before money can move, this guide is for you. The Afriex Business API has three core building blocks. They must be created in order, and each one produces an ID that the next step needs. This guide explains what each building block is, what ID it gives you, and exactly where that ID is used.

The big picture

Think of it like this: a Customer is the end user your business is acting on behalf of: the sender of a payout, or the payer of a deposit. A Payment Method holds the account on the other side: the recipient’s account for a payout, or the account you collect from for a deposit. A Transaction is the instruction to move money, and it needs to know on whose behalf you are acting and which account to use. Here is how the IDs connect:

ID quick-reference

ID field	Belongs to	Used in
`customerId`	Customer	Payment Method creation, Transaction creation
`paymentMethodId`	Payment Method	Transaction as `destinationId` or `sourceId`
`destinationId`	Transaction field	Equals a `paymentMethodId` (used in WITHDRAW)
`sourceId`	Transaction field	Equals a `paymentMethodId` (used in DEPOSIT)
`transactionId`	Transaction	Status lookups, webhook events

destinationId and sourceId in a Transaction are both Payment Method IDs. They are not special IDs. They are exactly the paymentMethodId value returned when you created the Payment Method. This is the single most common point of confusion.

Each building block explained

Customer

What it is: A Customer is the person or business your business is acting on behalf of: the sender of a payout, or the payer of a deposit. On a payout, Afriex passes the Customer’s details to the payout rail as the sender, and the Payment Method’s details as the recipient. For example, if you run a remittance app, each user who sends money home is a Customer, and the bank account they send to is a Payment Method linked to that Customer. The Customer record stores their identity information (name, email, phone, country) and is used to attribute transactions to the right person in your system. What ID it gives you: customerId When you use that ID:

Pass it as customerId when creating a Payment Method (to link the account to this person)
Pass it as customerId when creating a Transaction (to identify whose account is involved)

Fields to create a Customer:

Field	Required	Example
`fullName`	Yes	`"Amara Osei"`
`email`	Yes	`"amara@example.com"`
`phone`	Yes	`"+233201234567"` (E.164 format)
`countryCode`	Yes	`"GH"` (ISO 3166-1 alpha-2)

Payment Method

What it is: A Payment Method holds the account on the other side of the transaction: the recipient’s bank account, mobile money wallet, or other financial account for a payout, or the account you collect from for a deposit. It is linked to a Customer, the person on whose behalf you are acting. On a payout, the account belongs to the recipient, who is usually not the Customer. You need a Payment Method before you can send or receive money, because the Transaction needs to know exactly which account to credit or debit. What ID it gives you: paymentMethodId When you use that ID:

As destinationId in a WITHDRAW transaction (the account the money is sent to)
As sourceId in a DEPOSIT transaction (the account the money is pulled from)

A Payment Method has a type field, either WITHDRAW (used to send funds to a recipient) or DEPOSIT (used to collect funds from a customer). Make sure you create the right type for the transaction you plan to run.

Supported channels:

Channel	Description	Supports	Common use case
`BANK_ACCOUNT`	Local bank transfer	Withdraw	Payout to Nigerian GTBank, Kenyan KCB
`MOBILE_MONEY`	Mobile wallet	Deposit & Withdraw	MTN MoMo, M-Pesa, Airtel Money
`SWIFT`	International wire transfer	Withdraw	Cross-border payouts to Europe, US
`UPI`	Unified Payments Interface	Withdraw	Payouts to India
`INTERAC`	Interac e-Transfer	Deposit & Withdraw	Collections and payouts in Canada
`WE_CHAT`	WeChat Pay and Alipay	Withdraw	Payouts to China
`VIRTUAL_BANK_ACCOUNT`	Afriex-issued virtual account	Deposit	Receive collections in NGN, GHS, KES, and USD
`POOL_ACCOUNT`	Shared pool account	Deposit	Shared collection account (production only)
`CRYPTO_WALLET`	Crypto wallet	Deposit	USDC / USDT deposits

Virtual bank accounts

VIRTUAL_BANK_ACCOUNT is not created through the standard POST /api/v1/payment-method endpoint. It has two dedicated endpoints, and they do different things:

Create Virtual Account (POST /api/v1/payment-method/virtual-account) creates one. Pass currency, optionally customerId, and exactly one of label or amount.
List Virtual Accounts (GET /api/v1/payment-method/virtual-account) is read-only. It returns every active account for that customer and currency, and responds 200 with data: [] when none exist. It does not create one.

The GET endpoint used to create an account on the fly when none existed. It no longer does. If you are relying on that behavior, calling GET now returns an empty list rather than a new account, with no error. Call POST to create.

The two account shapes are chosen by which field you pass to POST:

Static (label): A permanent virtual bank account. The same account number is returned on every subsequent list for that customer and currency, and the customer can fund it at any time for any amount. label is one of SALES, OPERATIONS, PAYROLL, COLLECTIONS, VENDOR_PAYMENTS, TAX, REFUNDS, MARKETING, TREASURY, GENERAL.
Dynamic (amount): An account tied to a specific amount that expires after a set window (the response includes expiresInMinutes). Use this when collecting a specific payment within a defined time.

	Static	Dynamic
Triggered by	Passing `label`	Passing `amount`
Expires	Never	Yes (see `expiresInMinutes` in response)
Amount-specific	No	Yes

When you pass a customerId, virtual accounts are available in NGN and GHS. Other currencies for a specific customer are rejected with UNSUPPORTED_VIRTUAL_ACCOUNT_CURRENCY. There is also a cap on how many accounts a single business-customer-currency combination can hold; exceeding it returns VIRTUAL_ACCOUNT_LIMIT_REACHED.

POOL_ACCOUNT returns the business’s shared pool account for a country. Requires country; pass customerId to scope the response to a specific end-user. Use the reference on the response to reconcile incoming deposits. Virtual accounts are for your end customers. Link each one to a customerId so payments are attributed to the right person.

Transaction

What it is: A Transaction is the actual instruction to move money. It references a Customer and (depending on the type) one of their Payment Methods. What ID it gives you: transactionId When you use that ID:

To check the status: GET /api/v1/transaction/{transactionId}
It appears in webhook events so you can match notifications to records in your system

Three transaction types:

Type	What it does	Payment method needed
`WITHDRAW`	Send money from your Afriex wallet to a recipient’s account	`destinationId` (= paymentMethodId)
`DEPOSIT`	Pull money from a customer’s account into your Afriex wallet	`sourceId` (= paymentMethodId)
`SWAP`	Convert currency within your Afriex wallet	None

WITHDRAW: Your business wallet is the implicit source. Afriex debits your wallet automatically. You do not specify a source payment method.DEPOSIT: Your business wallet is the implicit destination. Afriex credits your wallet automatically. You do not specify a destination payment method.SWAP: Both source and destination are your business wallet. No customer or payment method IDs are needed at all.

The 3-step integration sequence

Here is the exact order of operations, with the IDs flowing from one step to the next.

Create the Customer

curl -X POST https://sandbox.api.afriex.com/api/v1/customer \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fullName": "Amara Osei",
    "email": "amara@example.com",
    "phone": "+233201234567",
    "countryCode": "GH"
  }'

Save the customerId from the response. You need it in the next step.

{
  "data": {
    "customerId": "69516dd0464b2213bd74cfad",
    "name": "Amara Osei",
    "email": "amara@example.com",
    "phone": "+233201234567",
    "countryCode": "GH"
  }
}

Create the Payment Method

Register the recipient’s bank account or mobile wallet (the account the money will be sent to or collected from). Link it to the Customer from Step 1 by passing their customerId.First, look up the correct institution code for the customer’s bank or mobile provider:

curl "https://sandbox.api.afriex.com/api/v1/payment-method/institution?channel=MOBILE_MONEY&countryCode=GH" \
  -H "x-api-key: YOUR_API_KEY"

Then create the payment method using the institutionCode and institutionName from that response:

curl -X POST https://sandbox.api.afriex.com/api/v1/payment-method \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": "69516dd0464b2213bd74cfad",
    "type": "WITHDRAW",
    "channel": "MOBILE_MONEY",
    "accountName": "Amara Osei",
    "accountNumber": "0201234567",
    "countryCode": "GH",
    "institution": {
      "institutionCode": "MTN",
      "institutionName": "MTN"
    }
  }'

Save the paymentMethodId from the response. This is what goes into destinationId (or sourceId) in your transaction.

{
  "data": {
    "paymentMethodId": "690df3281c11eea59108fcaf",
    "customerId": "69516dd0464b2213bd74cfad",
    "channel": "MOBILE_MONEY",
    "accountName": "Amara Osei",
    "accountNumber": "0201234567",
    "countryCode": "GH"
  }
}

Create the Transaction

Now create the transaction using both IDs from the previous steps.

customerId = the ID from Step 1
destinationId = the paymentMethodId from Step 2 (for a WITHDRAW)

curl -X POST https://sandbox.api.afriex.com/api/v1/transaction \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": "69516dd0464b2213bd74cfad",
    "type": "WITHDRAW",
    "destinationAmount": "91.50",
    "sourceCurrency": "USD",
    "destinationCurrency": "GHS",
    "destinationId": "690df3281c11eea59108fcaf",
    "meta": {
      "idempotencyKey": "550e8400-e29b-41d4-a716-446655440001",
      "reference": "ORDER-98765"
    }
  }'

Here the recipient gets exactly 91.50 GHS and the API works out the USD cost. To show that cost before you send, call Quote a Withdrawal first.The response includes a transactionId. Use it to track status or match incoming webhook events.

Transaction type payloads side by side

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "WITHDRAW",
  "destinationAmount": "16500",
  "sourceCurrency": "USD",
  "destinationCurrency": "NGN",
  "destinationId": "690df3281c11eea59108fcaf",
  "meta": {
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440001",
    "reference": "ORDER-001"
  }
}

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "DEPOSIT",
  "sourceAmount": "500",
  "sourceCurrency": "KES",
  "destinationCurrency": "USD",
  "sourceId": "690df3281c11eea59108fcc1",
  "meta": {
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440002",
    "reference": "COLLECTION-001"
  }
}

{
  "type": "SWAP",
  "sourceAmount": "500",
  "sourceCurrency": "USD",
  "destinationCurrency": "NGN",
  "meta": {
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440003",
    "reference": "SWAP-001"
  }
}

What changes between each type

Field	WITHDRAW	DEPOSIT	SWAP
`customerId`	Required	Required	Not required
`destinationId`	Required (= paymentMethodId)	Not used	Not used
`sourceId`	Not used	Required (= paymentMethodId)	Not used
`sourceAmount` / `destinationAmount`	Send the one you want exact; the API derives the other. If you send both, `destinationAmount` wins unless `shouldPreferSourceAmount` is `true`	Same as WITHDRAW	Exactly one. Sending both is rejected
`meta.idempotencyKey`	Required	Required	Required
`meta.reference`	Required	Required	Required

Payment method fields by channel

Different payment channels require different fields. Use the sections below to find the exact payload shape for your channel.

customerId is listed below for every channel because that is the usual case, but it is optional. Omit it and the payment method is attached to the business owner instead of an end customer. Pass it whenever the method belongs to one of your customers, which is almost always what you want.

BANK_ACCOUNT: Local bank transfer

Required fields: customerId, channel, accountName, accountNumber, countryCode, institution.institutionCode, institution.institutionNameTwo currencies differ:

EUR (IBAN): only institution.institutionName is required.
CNY (China): institution.institutionBranch is required as well.

Look up valid institution codes first: List InstitutionsYou can also verify the account holder name before creating: Resolve Payment Method

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "WITHDRAW",
  "channel": "BANK_ACCOUNT",
  "accountName": "John Doe",
  "accountNumber": "0123456789",
  "countryCode": "NG",
  "institution": {
    "institutionCode": "000013",
    "institutionName": "Guaranty Trust Bank (GTBank) Plc"
  }
}

MOBILE_MONEY: M-Pesa, MTN MoMo, Airtel, etc.

Required fields: customerId, channel, accountName, accountNumber (the mobile number), countryCode, institution.institutionName. Send the provider’s institution.institutionCode from List Institutions as well.Look up valid institution codes for the country: List Institutions

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "WITHDRAW",
  "channel": "MOBILE_MONEY",
  "accountName": "Amara Osei",
  "accountNumber": "0201234567",
  "countryCode": "GH",
  "institution": {
    "institutionCode": "MTN",
    "institutionName": "MTN"
  }
}

SWIFT: International wire transfer

Required fields: customerId, channel, accountName, accountNumber (IBAN or account number), countryCode, institution.institutionCode (SWIFT/BIC), institution.institutionName, institution.institutionAddress, recipient.recipientAddressSWIFT payouts are in USD, and need the correspondent (intermediary) bank too: institution.correspondentBankName and institution.correspondentBankAccountNumber.Use Institution Codes to resolve a SWIFT code to a bank name.

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "WITHDRAW",
  "channel": "SWIFT",
  "accountName": "John Doe",
  "accountNumber": "DE89370400440532013000",
  "countryCode": "DE",
  "institution": {
    "institutionCode": "DEUTDEDB",
    "institutionName": "Deutsche Bank",
    "institutionAddress": "Taunusanlage 12, 60262 Frankfurt am Main, Germany",
    "correspondentBankName": "Citibank N.A. New York",
    "correspondentBankAccountNumber": "10991234"
  },
  "recipient": {
    "recipientAddress": "Musterstrasse 1, 10115 Berlin, Germany"
  }
}

UPI: India

Required fields: customerId, channel, accountName, accountNumber (UPI ID / VPA), countryCode, recipient.recipientPhoneUPI takes no institution object.

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "WITHDRAW",
  "channel": "UPI",
  "accountName": "Raj Kumar",
  "accountNumber": "rajkumar@upi",
  "countryCode": "IN",
  "recipient": {
    "recipientPhone": "+919876543210"
  }
}

INTERAC: Canada

Required fields: customerId, channel, accountName, accountNumber (the email address registered for Interac), countryCode, recipient.recipientEmailInterac takes no institution object.

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "WITHDRAW",
  "channel": "INTERAC",
  "accountName": "John Doe",
  "accountNumber": "john.doe@email.com",
  "countryCode": "CA",
  "recipient": {
    "recipientEmail": "john.doe@email.com"
  }
}

WE_CHAT: China

Required fields: customerId, channel, accountName, accountNumber (phone number), countryCode, institution.institutionCode ("WECHAT"), institution.institutionName ("WECHAT"), recipient.recipientPhone

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "WITHDRAW",
  "channel": "WE_CHAT",
  "accountName": "Zhang Wei",
  "accountNumber": "+8613812345678",
  "countryCode": "CN",
  "institution": {
    "institutionCode": "WECHAT",
    "institutionName": "WECHAT"
  },
  "recipient": {
    "recipientPhone": "+8613812345678"
  }
}

Alipay: China

Alipay does not have a channel of its own. Create it on the WE_CHAT channel and set institution.institutionCode and institution.institutionName to ALIPAY; sending "channel": "ALIPAY" is rejected.Required fields: customerId, channel, accountName, accountNumber (Alipay-linked phone number or account ID), countryCode, institution.institutionCode, institution.institutionName

{
  "customerId": "69516dd0464b2213bd74cfad",
  "type": "WITHDRAW",
  "channel": "WE_CHAT",
  "accountName": "Zhang Wei",
  "accountNumber": "+8613812345678",
  "countryCode": "CN",
  "institution": {
    "institutionCode": "ALIPAY",
    "institutionName": "ALIPAY"
  }
}

VIRTUAL_BANK_ACCOUNT: Receive deposits

Virtual bank accounts are not created through the standard POST /api/v1/payment-method endpoint. Use the dedicated endpoint instead:

POST /api/v1/payment-method/virtual-account   # create one
GET  /api/v1/payment-method/virtual-account   # list existing ones (read-only)

POST creates the account; GET only lists what already exists and returns data: [] when there is none.Two shapes, determined by which field you pass to POST:

	Static	Dynamic
Pass	`label`	`amount`
Expires	Never	Yes, see `expiresInMinutes` in response
Amount-specific	No	Yes

With a customerId, NGN and GHS are supported. KES and USD accounts belong to your business, so omit customerId to create them.See Create Virtual Account and List Virtual Accounts for the full request and response reference.

Institution fields: which one to use and when

The institution object has several fields that look similar. Here is exactly what each one is and when you need it.

Field	What it is	When you need it
`institutionCode`	Short identifier for the bank or provider (e.g. `"000013"` for GTBank Nigeria, `"MTN"` for MTN Ghana)	Required for bank accounts, SWIFT, and WeChat Pay and Alipay. Optional for mobile money and EUR bank accounts. Not used for UPI or Interac.
`institutionName`	Human-readable display name (e.g. `"Guaranty Trust Bank (GTBank) Plc"`, `"MTN"`)	Required for every channel except UPI and Interac.
`institutionId`	Afriex’s internal database ID for the institution	Output only. Never pass this as input. It appears in responses but is not needed for creation.
`institutionAddress`	Physical address of the institution	Only for SWIFT transfers. Skip it for all other channels.
`institutionBranch`	The bank branch	Only for CNY bank accounts.
`correspondentBankName`, `correspondentBankAccountNumber`	The correspondent (intermediary) bank for a USD payout	Only for SWIFT transfers.

How to find the right institutionCode

Call GET /api/v1/payment-method/institution?channel=BANK_ACCOUNT&countryCode=NG
The response returns a list of institutions, each with institutionCode and institutionName
Copy those values directly into your Payment Method creation request

Nigerian banks are listed with their NIP code, such as 000013 for GTBank. The API also accepts the older three-digit CBN sort code, such as 058. For SWIFT and US routing numbers, use GET /api/v1/payment-method/institution/codes to resolve a known SWIFT/BIC code to a bank name.

Cache the institution list per country and channel. It changes infrequently and there is no need to fetch it on every Payment Method creation.

The meta object

Every transaction must include a meta object with two required fields. Without them, the API returns a 400 error.

"meta": {
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "ORDER-12345"
}

Field	Required	What it does
`idempotencyKey`	Yes	A unique string you generate per transaction attempt. If a transaction already exists with this key, Afriex rejects the request with `409 DUPLICATE_REQUEST` rather than creating a duplicate. It does not replay the original transaction. Use a UUID v4.
`reference`	Yes	Your own internal ID for this transaction (e.g. order number, payment ID, or invoice reference). Used for reconciliation and returned on the transaction as `merchantReference`.
`narration`	No	A human-readable description (e.g. `"Salary payment for March 2025"`).
`invoice`	Required for SWIFT withdrawals; otherwise No	An S3 object key for the invoice document. Upload the file via Generate Upload URL first, then pass the returned `key` here. The object must already exist in storage when the transaction is created.

Never reuse an idempotencyKey across different transaction attempts. Use a fresh UUID for every new transaction. Reusing a key, or reusing a reference, is rejected with 409 DUPLICATE_REQUEST and the new transaction is not created.Because a duplicate is an error rather than a replay, a 409 is not a failure to retry. It means a transaction for that key already exists. Look it up with List Transactions filtered by your merchantReference to find out what happened to it, instead of retrying with a fresh key and risking a genuine double payment.

Common mistakes

1. Using a customerId as destinationId or sourceId

destinationId and sourceId must be a paymentMethodId, not a customerId. Both look like hex strings, which makes it easy to mix them up.

// Wrong: this is a customerId
"destinationId": "69516dd0464b2213bd74cfad"

// Correct: this is the paymentMethodId from Step 2
"destinationId": "690df3281c11eea59108fcaf"

2. Skipping the 3-step sequence

You cannot create a Transaction without first creating a Customer and a Payment Method. The API returns a 404 or 400 if either does not exist. Always follow: Customer → Payment Method → Transaction.

3. Mixing up DEPOSIT and WITHDRAW fields

WITHDRAW uses destinationId (where the money goes)
DEPOSIT uses sourceId (where the money comes from)

Passing destinationId on a DEPOSIT (or sourceId on a WITHDRAW) will cause the API to reject the request.

4. Assuming SWAP needs a payment method

SWAP does not touch any external account. It converts currency inside your Afriex business wallet. No customerId, destinationId, or sourceId is needed. Only the currency pair and the meta object are required.

{
  "type": "SWAP",
  "sourceAmount": "500",
  "sourceCurrency": "USD",
  "destinationCurrency": "NGN",
  "meta": {
    "idempotencyKey": "unique-uuid-here",
    "reference": "SWAP-001"
  }
}

5. Omitting meta.idempotencyKey or meta.reference

Both are required on every transaction. The API returns a 400 if either is missing. Always generate a fresh UUID for idempotencyKey and use your own internal order or payment ID as reference.

6. Hardcoding institution codes without looking them up

Do not guess institution codes. Use GET /api/v1/payment-method/institution?channel=BANK_ACCOUNT&countryCode=NG to get the correct code for each country and channel. The same bank can have a different code in different countries.

7. Passing institutionId as input

institutionId is an output field. It appears in API responses but you never need to supply it when creating a Payment Method. The fields you pass are institutionCode and institutionName.

Tracking what happens after you create a transaction

Transactions do not complete instantly. After creation the status will be PENDING or PROCESSING. Here is how to know when it finishes.

Testing in sandbox? Sandbox transactions settle automatically in about 5 minutes. Pick the outcome with the payment method’s last four digits (e.g. 0001 for fail, 0003 to hold in PENDING until you call /simulate); add SIMULATE_INSTANT anywhere in meta.reference to speed things up to about 30 seconds. Full reference: Testing in Sandbox.

Option A (recommended): Webhooks Subscribe to TRANSACTION.UPDATED events. Afriex sends an HTTP POST to your webhook URL with the full transaction payload whenever the transaction’s status changes. This fires on intermediate statuses too, not just terminal ones, so expect several deliveries for a single transaction. Branch on the payload’s status field to decide whether the transaction is actually finished. See Webhook setup for configuration steps and payload examples. Option B: Poll the status endpoint

curl "https://sandbox.api.afriex.com/api/v1/transaction/TRANSACTION_ID" \
  -H "x-api-key: YOUR_API_KEY"

Prefer webhooks over polling. Polling adds latency and uses API quota. Webhooks notify you the moment the status changes.

Terminal statuses

Status	Meaning
`SUCCESS`	Transaction finished successfully
`FAILED`	Transaction could not be processed. Check `meta.failureReason.code` for a stable `AFX_*` reason (see Failure reasons).
`CANCELLED`	Cancelled before processing started
`REFUNDED`	Funds returned to the sender
`REJECTED`	Rejected after manual review

Next steps

Quickstart

Make your first API call in under 5 minutes.

Create a Customer

Full parameter reference for customer creation.

Create a Payment Method

All channels and required fields in the API reference.

Create a Transaction

Full transaction creation reference with all fields.

Data Model Reference

Complete field-by-field documentation for all models.

Webhooks

Receive real-time transaction status updates.

Getting started

Core Concepts

Testing

What this guide covers

The big picture

ID quick-reference

Each building block explained

Customer

Payment Method

Virtual bank accounts

Transaction

The 3-step integration sequence

Transaction type payloads side by side

What changes between each type

Payment method fields by channel

Institution fields: which one to use and when

How to find the right institutionCode

The meta object

Common mistakes

1. Using a customerId as destinationId or sourceId

2. Skipping the 3-step sequence

3. Mixing up DEPOSIT and WITHDRAW fields

4. Assuming SWAP needs a payment method

5. Omitting meta.idempotencyKey or meta.reference

6. Hardcoding institution codes without looking them up

7. Passing institutionId as input

Tracking what happens after you create a transaction

Terminal statuses

Next steps

Quickstart

Create a Customer

Create a Payment Method

Create a Transaction

Data Model Reference

Webhooks

​What this guide covers

​The big picture

​ID quick-reference

​Each building block explained

​Customer

​Payment Method

​Virtual bank accounts

​Transaction

​The 3-step integration sequence

​Transaction type payloads side by side

​What changes between each type

​Payment method fields by channel

​Institution fields: which one to use and when

​How to find the right institutionCode

​The meta object

​Common mistakes

​1. Using a customerId as destinationId or sourceId

​2. Skipping the 3-step sequence

​3. Mixing up DEPOSIT and WITHDRAW fields

​4. Assuming SWAP needs a payment method

​5. Omitting meta.idempotencyKey or meta.reference

​6. Hardcoding institution codes without looking them up

​7. Passing institutionId as input

​Tracking what happens after you create a transaction

​Terminal statuses

​Next steps

Quickstart

Create a Customer

Create a Payment Method

Create a Transaction

Data Model Reference

Webhooks

What this guide covers

The big picture

ID quick-reference

Each building block explained

Customer

Payment Method

Virtual bank accounts

Transaction

The 3-step integration sequence

Transaction type payloads side by side

What changes between each type

Payment method fields by channel

Institution fields: which one to use and when

How to find the right institutionCode

The meta object

Common mistakes

1. Using a customerId as destinationId or sourceId

2. Skipping the 3-step sequence

3. Mixing up DEPOSIT and WITHDRAW fields

4. Assuming SWAP needs a payment method

5. Omitting meta.idempotencyKey or meta.reference

6. Hardcoding institution codes without looking them up

7. Passing institutionId as input

Tracking what happens after you create a transaction

Terminal statuses

Next steps