Customers

A customer is one of your end users. You create them, you own the relationship, and StableMint never contacts them. What StableMint does is hold and attribute their money: incoming payments are reconciled to the right customer, and their deposits and withdrawals are tracked separately from your own. In the API they are simply customers. Internally you may see them called customers.

Two ways to attribute an incoming payment

This is the first decision to make, and it has a cost attached.

A virtual IBAN per customer

Provision each customer their own IBAN. Anything arriving at it is attributed to that customer automatically — no reference needed, nothing for the payer to get wrong.

A shared IBAN plus a reference

Customers pay into your account and quote a reference you generated. You call the deposit endpoint first to mint that reference, then reconcile on it.

Virtual IBANs are chargeable. Each one carries a cost that StableMint passes through to you. A reference-based deposit does not. For a customer who pays once, the reference is usually right; for one who pays repeatedly, the dedicated IBAN pays for itself in reconciliation you no longer have to do.

You can mix both across your customer base, and a customer with a virtual IBAN can still be sent a reference-based deposit.

Create a customer

curl -X POST https://api.stablemint.net/v1/customers \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerCustomerIdentifier": "acct_88213",
    "email": "maria@example.com",
    "kyc": {
      "customerType": "Individual",
      "fullName": "Maria Silva",
      "residenceAddress": "Rua Augusta 12, 1100-048 Lisboa, Portugal",
      "citizenshipCountryCode": "PT",
      "dateOfBirth": "1988-04-02"
    }
  }'

partnerCustomerIdentifier is your identifier for this person. Pass the primary key you already use and every StableMint record stays joinable to your own database. StableMint returns its own guid, which is what the rest of the API takes.

Field	Required	Notes
`partnerCustomerIdentifier`	Yes	Your id for the customer.
`email`	No
`kyc.customerType`	Yes	`Individual` or `Business`.
`kyc.fullName`	Yes	Legal name for an individual, registered name for a business.
`kyc.residenceAddress`	Yes
`kyc.citizenshipCountryCode`	Yes	ISO 3166-1 alpha-2.
`kyc.dateOfBirth`	No	Individuals.
`kyc.mobilePhone`	No
`kyc.personalIdentificationNumber`	No
`kyc.uboFirstName1–5` / `uboLastName1–5`	No	Beneficial owners, for `Business` customers. Up to five.

Send only what you are asked for. Every additional identity field you pass is personal data StableMint then holds on your behalf, and it widens your obligations under GDPR without widening what the platform can do for you.

Provision a virtual IBAN

curl -X POST https://api.stablemint.net/v1/customers/{id}/account \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE"

The account is opened in the customer’s name. The response carries an iban and country, plus an ibans array — a customer may end up with more than one IBAN, in different countries, all feeding the same underlying balance.

Get the identity right before you provision. The virtual IBAN is opened using the customer’s KYC details, so changing those details afterwards does not re-issue the account. Updating a customer who already holds a virtual IBAN is restricted for this reason — treat the identity as settled at the point you call this endpoint.

Create a reference-based deposit

For customers without their own IBAN. You tell StableMint a payment is expected; it returns the reference and the account to pay into.

curl -X POST https://api.stablemint.net/v1/customers/{id}/deposit \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2500.00, "currency": "EUR", "idempotencyKey": "dep-2026-09-14-001" }'

{
  "customerId": "8f2c...",
  "amount": 2500.00,
  "currency": "EUR",
  "reference": "SM-4K2P-9QX7",
  "publicReference": "SM-4K2P-9QX7",
  "status": "Pending",
  "expiresAt": "2026-09-21T23:59:59Z",
  "fundingInstructions": {
    "beneficiaryName": "Acme Payments Ltd",
    "bankName": "Example Bank",
    "iban": "MT00XXXX00000000000000000000",
    "bic": "XXXXMTMT"
  }
}

Show fundingInstructions and publicReference to your customer verbatim. A payment that arrives without the reference, or after expiresAt, has nothing to match against and needs manual reconciliation. Always send an idempotencyKey — a retried call with the same key returns the original deposit instead of creating a second one.

Customer balances are not spendable balances

The customerActivity figures on GET /v1/accounts are deposit, withdrawal and net figures — not an authoritative balance, and they are aggregate across your customers rather than per customer.StableMint knows what came in and what went out. It does not know about anything that changed a customer’s position without moving through the platform: winnings, losses, yield you pay, fees you charge. If your product does any of those, customerBalance is not what your customer can spend, and you must keep that figure yourself.

There is no per-customer balance endpoint. To reconstruct one customer’s position, list their transactions and sum them yourself — see below. For a straightforward pass-through model — money in, money out, nothing else — net deposits and the spendable balance are the same number, and you can use it directly. Confirm that describes your product before you rely on it.

Listing a customer’s transactions

Use the transactions endpoint with a filter rather than a customer-scoped path:

# every customer's completed transactions
curl "https://api.stablemint.net/v1/transactions?scope=Customer&status=Completed" \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE"

For a single customer, add partnerCustomerGuid:

curl "https://api.stablemint.net/v1/transactions?scope=Customer&partnerCustomerGuid=3f2a9c14-7b5e-4d21-9c6a-8e0f1d2b3c45" \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE"

See Transactions for the full filter set.

Get started

Authentication

Core resources

Accept payments

Send money

Webhooks

Feed

Cross-chain bridge

Two ways to attribute an incoming payment

A virtual IBAN per customer

A shared IBAN plus a reference

Create a customer

Provision a virtual IBAN

Create a reference-based deposit

Customer balances are not spendable balances

Listing a customer’s transactions

​Two ways to attribute an incoming payment

A virtual IBAN per customer

A shared IBAN plus a reference

​Create a customer

​Provision a virtual IBAN

​Create a reference-based deposit

​Customer balances are not spendable balances

​Listing a customer’s transactions

Two ways to attribute an incoming payment

Create a customer

Provision a virtual IBAN

Create a reference-based deposit

Customer balances are not spendable balances

Listing a customer’s transactions