Skip to main content
Most connectors are quoted and then initiated. Bespoke connectors work the other way round: the customer pays the provider first, and the payment pays out to one of your wallets. You don’t quote or initiate these payments. Instead you set the customer up once:
  1. Register the customer with the connector’s provider, if the provider requires it.
  2. Register an on-ramp reference for the customer, bound to one of your wallets.
  3. Give the customer what they pay against. Every payment on it pays out to that wallet.
All examples assume the two headers every protected request sends, as in Your first transaction:

Find a bespoke connector

List connectors with flow=BESPOKE. Every filter is optional; add countryIsoCode2, method, or direction to narrow the list.
cURL
Each connector in the response carries flow. Keep the id of the one you want; the next steps call it connectorId. Responses from the reference endpoints return the same id as routeId.

Register the customer (if the provider requires it)

Some providers, for example Noah, verify the customer themselves before they accept payments, and refuse a reference for a customer they don’t know. EasyPay doesn’t, so skip this step for EasyPay.customerId is your own id for the customer. It only needs to be unique within your association. Only returnUrl is required, and it must be an https URL; any other fields you send prefill the provider’s onboarding.
cURL
The status in the response tells you what to do next:Registering the same customerId again returns its current status. To be told when the provider decides, subscribe to Customer_Verified and Customer_Rejected. Use register/business for a business customer; it also requires a two-letter registrationCountry.

Register a reference

Bind a reference to one of your wallets. settlementAccount is the wallet’s Stellar public key, from GET /v1/wallets, and the wallet needs a trustline for the connector’s settlement asset.
cURL
What the customer pays against depends on the provider. For EasyPay it is the reference itself, the EasyPay number. For Noah it is the payment details in metadata, for example the bank account to transfer to. Providers that issue more than one reference per customer return the rest in relatedReferences, each with its own reference and metadata.

Track payments

Payments on a reference are not submitted by you, so they have no transaction record. Follow them with webhooks: each payment raises the usual Intent* events, and on its lifecycle events metaData.data carries the payout summary (netAmount, totalFees, assetCode) and the onrampReference it arrived on. Once settled, the payout also shows in the wallet’s balance and statement.

​
Move references to another wallet

Rebinding changes where future payments land. The new settlement account must also be one of your wallets, with a trustline for the settlement asset.
  • Move every reference a customer has on a connector: PUT /v1/onramp/references with connectorId, customerId and settlementAccount.
  • Move a single reference: PUT /v1/onramp/references/{reference} with settlementAccount.

​
List references

GET /v1/onramp/references filters by customerId, settlementAccount, and connectorId. Unlike the other collections, it pages with pageNumber and pageSize (up to 100) and returns {data, pageNumber, pageSize, count}, where count is the total number of matches.