FlyraAPI v1
Flyra API Platform · Partner reference

Stablecoin‑backed Payment Infrastructure for businesses and individuals.

Everything a partner needs to onboard business and individual customers to Flyra, verify them, open accounts for them, quote exchange rates and move money on their behalf.

Base URL https://api.flyra.com
22 endpoints
23 webhook event types
OAuth 2.0 client credentials
1 · Introduction

Context

Flyra provides an API platform that lets businesses and individuals anywhere in the world onboard and obtain stablecoin‑backed wallets and payment instruments. Flyra handles KYC verification and compliance for every customer, whether a business or an individual, through an onboarding platform that works with KYC verification providers and banking partners.

Once a customer is approved, it has a Flyra wallet, and you can open virtual accounts for it to receive funds in USD, EUR, GBP and MXN, and link its bank and mobile money accounts for deposits and payouts.

This reference is written for Flyra's partners, who call the API on behalf of their own customers. For example, a payment service provider onboards its merchants as business customers, and an organization onboards its employees as individual customers, for instance to offer them remittances. In each case you create the customer records, start verification, and then create instruments and transfers for them.

The Partner API is a JSON API over HTTPS, authenticated with OAuth 2.0 client credentials.

Onboard customers

Create business customers with the owners and representatives connected to them, or individual customers on their own.

Verify with KYC

Add documents and due-diligence answers, then start verification. Flyra runs the checks and reports the result.

Open instruments

A Flyra wallet for every approved customer, virtual accounts in USD, EUR, GBP and MXN, and linked bank and mobile money accounts.

Move money

Quote a rate, create transfers between instruments and follow their status through webhooks.

1 · Get started

Get sandbox keys

You build and test in the sandbox and go live when you are ready. The two are fully separate: API credentials, webhook endpoints and data belong to one environment, so a sandbox credential never works live, and a customer created in the sandbox does not exist live.

  1. Sign in to the Partner Dashboard. Use the account you just created.
  2. Create API credentials. On the API credentials page, create a credential with the scopes your integration needs. Copy the client secret straight away: it is shown once.
  3. Get an access token. Exchange the client ID and secret at the token URL, then send the token with every call. A 200 with a list of networks from GET /v1/bank-networks (scope payment_instruments:read) means your credential, token and base URL are all set up.
API base URLhttps://api.flyra.com
Token URLhttps://api.flyra.com/v1/oauth2/token
LiveIts own credentials, separate from your sandbox ones. Go live once your integration handles errors, retries and webhooks as this reference describes.
The examples in this reference call https://api.flyra.com. They read your credentials from FLYRA_CLIENT_ID and FLYRA_CLIENT_SECRET, and the current access token from FLYRA_ACCESS_TOKEN.
Quick start
# Exchange your client ID and secret for a token
curl -X POST "https://api.flyra.com/v1/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id="$FLYRA_CLIENT_ID" \
  --data-urlencode client_secret="$FLYRA_CLIENT_SECRET"

# Call the API with the access_token from the answer
curl -X GET "https://api.flyra.com/v1/bank-networks?country=NG" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"

Add test money

A wallet starts empty, and transfers out of it, and a virtual account's setup fee where one is due, are paid from it. In the sandbox a deposit needs no real payment: create one into the customer's wallet with POST /v1/transfers and it settles without anything being paid in.

Sandbox deposit into the wallet
curl -X POST "https://api.flyra.com/v1/transfers" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: 5d2e8f1a-7b3c-4e9d-a0f6-1c8b4e7a2d93" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "source": {
    "type": "PROVIDED_BANK_ACCOUNT",
    "currency": "NGN",
    "amount": "50000.00"
  },
  "destination": {
    "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e",
    "currency": "USD"
  }
}'
2 · Core models

How the API fits together

Everything starts from a customer, which is either a business or an individual. For a business, the people connected to it are customers too, linked through related parties. Documents, due-diligence answers and a KYC verification establish trust; accounts, payment instruments and transfers move money.

Customer of type BUSINESS

Customer of type INDIVIDUAL

An individual customer in their own right, such as an employee onboarded by their organization, uses the same models without related parties.

Customer

A business, or an individual: either a person associated with a business, or a customer in their own right. The type field is BUSINESS or INDIVIDUAL.

Related party

Links an individual customer to a business as an owner, director, signer or other role. Business customers only.

Document

Files collected for verification: for a business and the individuals associated with it, or for an individual customer.

Due diligence

Answers about where a customer's money comes from and what the account is for. Most customers need them before KYC.

KYC verification

The verification of a customer. It starts PENDING and ends APPROVED or DECLINED.

Account

A customer's account with Flyra and its balances. The FLYRA_WALLET account is created on KYC approval.

Payment instrument

What a transfer names as its source or destination: the customer's Flyra wallet, virtual accounts and linked accounts.

Transfer

A movement of funds between instruments, accounts outside Flyra, and one-time deposit accounts Flyra creates for it.

Supported legal structures for Business

A business customer must have one of these legal structures, sent in legalStructure as SOLE_PROPRIETORSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, LIMITED_LIABILITY_PARTNERSHIP, CORPORATION, LIMITED_LIABILITY_COMPANY, TRUST, COOPERATIVE, NONPROFIT_ORGANIZATION, FOUNDATION, DAO or OTHER.

Model reference

Ids are generated by Flyra and read-only: leave them out of create requests and Flyra returns them in the response. Nested addresses, contacts and identifiers get their own id too.

Customer

A business or an individual. Fields marked BUSINESS only or INDIVIDUAL only are refused on the other type.

AttributeTypeRequiredDescription
businessDescriptionstringNoBUSINESS only.
citizenshipsarray of objectsNoCountries the person is a citizen of. INDIVIDUAL only; refused with 422 on a BUSINESS.
citizenships[].countrystringYesISO 3166-1 alpha-2 country code.
citizenships[].idstring (uuid)No
countryOfRegistrationstringNoBUSINESS only. The country the business is registered in, ISO 3166-1 alpha-2. It writes the same value as countryOfResidence, so send one of the two; both with different values is refused with 422.
countryOfResidencestringConditionalISO 3166-1 alpha-2 country code. For an INDIVIDUAL, where they live; for a BUSINESS, where it is registered. Required for both.
dateOfBirthstring (date)NoINDIVIDUAL only.
doingBusinessAsstringNoBUSINESS only.
emailAddressarray of objectsYesAt least one, for both customer types. On a BUSINESS it is the company's own address, not any individual's.
emailAddress[].emailstring (email)Yes
emailAddress[].idstring (uuid)No
emailAddress[].typeenumYesPERSONAL is a person's own contact; WORK is a person's work contact; BUSINESS belongs to a business customer rather than to anyone at it.
PERSONALWORKBUSINESS
idstring (uuid)Read-onlyUnique id generated by Flyra. Referred to as customerId elsewhere.
incorporatedAtstring (date)NoDate of incorporation. BUSINESS only.
indClassificationCodestringNoIndustry classification code of the business, for example a NAICS code. BUSINESS only.
internalCustomerIdstringNoThe caller's own id for this customer. Stored and returned unchanged, so a partner can match a Flyra customer back to their own record.
legalNamestringConditionalRequired for BUSINESS; rejected for INDIVIDUAL.
legalStructureenumConditionalThe business's legal form. Required for a BUSINESS; refused on an INDIVIDUAL.
SOLE_PROPRIETORSHIPGENERAL_PARTNERSHIPLIMITED_PARTNERSHIPLIMITED_LIABILITY_PARTNERSHIPCORPORATIONLIMITED_LIABILITY_COMPANYTRUSTCOOPERATIVENONPROFIT_ORGANIZATIONFOUNDATIONDAOOTHER
nameobjectConditional
name.firstNamestringYes
name.lastNamestringYes
name.middleNamestringNo
nationalIdentifiersarray of objectsConditionalAt least one is required before KYC can start. Deposits in NG, KE and UG also need particular types: an INDIVIDUAL in NG needs both BVN and NIN, in KE PIN, in UG TIN; a BUSINESS there needs CAC and TIN. A customer without them is only stopped at their first deposit, so send them now or add them with PATCH. Other corridors, and payouts, need nothing beyond the identifier KYC requires.
nationalIdentifiers[].documentobjectConditionalThe photo behind this identifier, sent with it instead of uploaded first: Flyra stores it and returns its documentId. Required for anyone linked to a BUSINESS as a related party; recommended for everyone else.
nationalIdentifiers[].document.documentContentstringYesThe file as a data URI, for example data:image/jpeg;base64,/9j/4AAQ...
nationalIdentifiers[].document.documentTypeenumYesBUSINESS_FORMATION, BUSINESS_OWNERSHIP and the other business values apply to BUSINESS customers only. The identity types, PASSPORT through SELFIE, belong to an INDIVIDUAL and are the photo behind a nationalIdentifiers entry.
PROFILE_PICTUREPROOF_OF_ADDRESSGOVERNMENT_IDPASSPORTSTATE_IDVOTER_IDNATIONAL_IDDRIVING_LICENSESELFIEBUSINESS_FORMATIONBUSINESS_OWNERSHIPFORMATION_DOCUMENTOWNERSHIP_DOCUMENTTAX_ID_DOCUMENTPROOF_OF_BUSINESS_ADDRESSPROOF_OF_BUSINESS_ACTIVITYOWNER_ID_PHOTOOTHER
nationalIdentifiers[].document.namestringConditionalOriginal file name, kept for metadata only.
nationalIdentifiers[].documentIdstring (uuid)NoId of a document already added with POST /v1/customers/{customerId}/documents. Send this or document, not both.
nationalIdentifiers[].expiryDatestring (date)No
nationalIdentifiers[].idstring (uuid)No
nationalIdentifiers[].issuingCountrystringYesISO 3166-1 alpha-2 country code.
nationalIdentifiers[].nationalIdstringYes
nationalIdentifiers[].typeenumYesOne list for national and tax identifiers. BRN is a business registration number, CRN a company registration number, CNPJ a Brazilian company's federal registration number, and OTHER a registration number of any other kind.
PASSPORTSTATE_IDVOTER_IDDRIVING_LICENSESSNNINTINBVNRFCNINOPINSPIITRNATIONAL_IDNIRFOREIGN_TAX_IDCPFNITNIENIFCACVATEINITINUNKNOWNBRNCRNCNPJOTHER
operatingAddressobjectNo
operatingAddress.addressLine1stringYesStreet address.
operatingAddress.addressLine2stringNoSuite, floor or apartment.
operatingAddress.citystringYes
operatingAddress.countrystringYesISO 3166-1 alpha-2 country code.
operatingAddress.idstring (uuid)No
operatingAddress.postalCodestringNo
operatingAddress.statestringYes
operatingAddress.typeenumYesRESIDENTIAL belongs to an INDIVIDUAL; BUSINESS_OPERATING and BUSINESS_REGISTERED to a BUSINESS.
RESIDENTIALBUSINESS_OPERATINGBUSINESS_REGISTERED
phoneNumberarray of objectsYesAt least one, for both customer types. On a BUSINESS it is the company's own number, not any individual's.
phoneNumber[].idstring (uuid)No
phoneNumber[].numberstringYesE.164 format.
phoneNumber[].typeenumYesPERSONAL is a person's own contact; WORK is a person's work contact; BUSINESS belongs to a business customer rather than to anyone at it.
PERSONALWORKBUSINESS
registeredAddressobjectNo
registeredAddress.addressLine1stringYesStreet address.
registeredAddress.addressLine2stringNoSuite, floor or apartment.
registeredAddress.citystringYes
registeredAddress.countrystringYesISO 3166-1 alpha-2 country code.
registeredAddress.idstring (uuid)No
registeredAddress.postalCodestringNo
registeredAddress.statestringYes
registeredAddress.typeenumYesRESIDENTIAL belongs to an INDIVIDUAL; BUSINESS_OPERATING and BUSINESS_REGISTERED to a BUSINESS.
RESIDENTIALBUSINESS_OPERATINGBUSINESS_REGISTERED
residentialAddressobjectNo
residentialAddress.addressLine1stringYesStreet address.
residentialAddress.addressLine2stringNoSuite, floor or apartment.
residentialAddress.citystringYes
residentialAddress.countrystringYesISO 3166-1 alpha-2 country code.
residentialAddress.idstring (uuid)No
residentialAddress.postalCodestringNo
residentialAddress.statestringYes
residentialAddress.typeenumYesRESIDENTIAL belongs to an INDIVIDUAL; BUSINESS_OPERATING and BUSINESS_REGISTERED to a BUSINESS.
RESIDENTIALBUSINESS_OPERATINGBUSINESS_REGISTERED
taxIdentifiersarray of objectsNoStored with nationalIdentifiers as one set, so an identifier reads back under whichever of the two lists its type belongs to.
taxIdentifiers[].expiryDatestring (date)No
taxIdentifiers[].idstring (uuid)No
taxIdentifiers[].issuingCountrystringYesISO 3166-1 alpha-2 country code.
taxIdentifiers[].taxIdstringYes
taxIdentifiers[].typeenumYesOne list for national and tax identifiers. BRN is a business registration number, CRN a company registration number, CNPJ a Brazilian company's federal registration number, and OTHER a registration number of any other kind.
PASSPORTSTATE_IDVOTER_IDDRIVING_LICENSESSNNINTINBVNRFCNINOPINSPIITRNATIONAL_IDNIRFOREIGN_TAX_IDCPFNITNIENIFCACVATEINITINUNKNOWNBRNCRNCNPJOTHER
termsAcceptedAtstring (date-time)NoWhen the customer accepted Flyra's terms of service, as you recorded it. It must be present before KYC starts, or the verification is refused with 422; send it here or add it later with PATCH.
typeenumYes
BUSINESSINDIVIDUAL
websitestringNoBUSINESS only.

Document

A file added to a customer for verification. The file itself is not returned.

AttributeTypeRequiredDescription
documentTypeenumYesBUSINESS_FORMATION, BUSINESS_OWNERSHIP and the other business values apply to BUSINESS customers only. The identity types, PASSPORT through SELFIE, belong to an INDIVIDUAL and are the photo behind a nationalIdentifiers entry.
PROFILE_PICTUREPROOF_OF_ADDRESSGOVERNMENT_IDPASSPORTSTATE_IDVOTER_IDNATIONAL_IDDRIVING_LICENSESELFIEBUSINESS_FORMATIONBUSINESS_OWNERSHIPFORMATION_DOCUMENTOWNERSHIP_DOCUMENTTAX_ID_DOCUMENTPROOF_OF_BUSINESS_ADDRESSPROOF_OF_BUSINESS_ACTIVITYOWNER_ID_PHOTOOTHER
idstring (uuid)Read-only
namestringNoOriginal file name, kept for metadata only.

KYC verification

The verification of a customer. PENDING_USER_ACTION means it cannot proceed until you collect something further from the customer.

AttributeTypePresentDescription
customerIdstring (uuid)Always
idstring (uuid)Always
statusenumAlwaysPENDING_USER_ACTION means the verification cannot proceed until the partner collects something further from the customer.
PENDINGIN_PROGRESSPENDING_USER_ACTIONIN_REVIEWAPPROVEDDECLINED

Account

A customer's account with Flyra and the balances it holds. Read-only.

AttributeTypePresentDescription
accountNumberstringWhen setThe account's own number, in full. You hold your customer's banking relationship and need it to reconcile.
balancesarray of objectsWhen set
balances[].amountstringAlwaysDecimal string, for example "48250.00".
balances[].currencystringAlwaysCan differ from the account's currency: a wallet balance on a USD account is reported as USDB, the stablecoin it settles in. Expect both USD and USDB.
balances[].typeenumAlwaysAVAILABLE can be spent; RESTRICTED is held. CURRENT and RECEIVABLE are reported under their own names.
AVAILABLERESTRICTEDCURRENTRECEIVABLE
currencystringWhen setThe account's own currency, which may differ from its balances' currency.
idstring (uuid)Always
openedOnstring (date)When set
statusenumAlways
ACTIVEIN_ACTIVEFROZENCLOSED
typeenumWhen setFLYRA_WALLET is the stablecoin-backed wallet created on KYC approval. The other values name the kind of account as Flyra records it.
FLYRA_WALLETCHECKINGFIAT_DEPOSITCRYPTO_DEPOSITPREPAID_CARDLOAN

Payment instrument

An instrument a transfer can name as its source or destination. Read and list calls return this shape; the create call returns it with accountId. To create one, see Create a payment instrument.

AttributeTypePresentDescription
accountIdstring (uuid)When setThe account the instrument belongs to, as GET /accounts reports it.
countrystringWhen setISO 3166-1 alpha-2 country the instrument belongs to.
currencystringWhen set
idstring (uuid)AlwaysName this as a transfer's source or destination.
instrumentDetailsobjectWhen setThe instrument's own details. Which fields are present depends on instrumentType and the corridor; see the table below. Absent while a provisioned account is still PENDING.
instrumentTypeenumAlwaysOWNED_ instruments are provisioned by Flyra for the customer; LINKED_ instruments are accounts outside Flyra that the customer pays or is paid by. OWNED_WALLET_ACCOUNT is the Flyra wallet every approved customer has. The value you send on a create is the value you read back.
LINKED_BANK_ACCOUNTOWNED_BANK_ACCOUNTOWNED_VIRTUAL_BANK_ACCOUNTLINKED_MOBILE_MONEY_ACCOUNTOWNED_WALLET_ACCOUNTLINKED_CRYPTO_ADDRESSOWNED_CRYPTO_ADDRESSDEBIT_CARDCREDIT_CARD
isDefaultbooleanWhen set
nickNamestringWhen setWhat the customer calls it, when they have named it.
statusenumAlways
ACTIVEIN_ACTIVEDELETED
instrumentTypeFields in instrumentDetails
OWNED_VIRTUAL_BANK_ACCOUNT, USaccountNumber, routingNumber, accountType, beneficiaryName, beneficiaryAddress, bankName, bankAddress, paymentRails
OWNED_VIRTUAL_BANK_ACCOUNT, GBaccountNumber, sortCode, accountHolderName, bankName, paymentRails
OWNED_VIRTUAL_BANK_ACCOUNT, EUiban, bic, accountHolderName, bankName, paymentRails
OWNED_VIRTUAL_BANK_ACCOUNT, MXclabe, accountHolderName, bankName, paymentRails
LINKED_BANK_ACCOUNTaccountNumber with routingNumber, sortCode, iban with bic, clabe or the corridor's own key; bankCode and networkName in NG, KE, UG and ZA; bankName
LINKED_MOBILE_MONEY_ACCOUNTaccountNumber (the registered phone number), bankCode, networkName
OWNED_WALLET_ACCOUNT, LINKED_CRYPTO_ADDRESS, OWNED_CRYPTO_ADDRESSwalletAddress, chain
DEBIT_CARD, CREDIT_CARDlast4Digits only. A card number is never returned.

Transfer

A movement of funds. Each side has its own currency and amount, so a transfer can change currency.

AttributeTypeRequiredDescription
createdTimestring (date-time)Read-onlyWhen Flyra accepted the transfer. ISO 8601, UTC.
customerIdstring (uuid)YesThe customer the transfer is initiated for.
destinationobjectYesOne end of the transfer, with its own currency and amount, so a transfer can change currency. Identify it by paymentInstrumentId or by type, not both. instrumentType and country are not accepted.
destination.amountstringNoDecimal string in this side's currency. Send it on the source only: Flyra prices the transfer from it and fills in the destination amount, which is ignored on a request.
destination.bankAccountDetailsobjectNoReturned when this side's type is PROVIDED_BANK_ACCOUNT: where the customer pays in to complete the deposit. The fields present follow bankAccountType. The transfer stays PENDING until the customer pays.
destination.bankAccountDetails.accountHolderNamestringNoEvery type.
destination.bankAccountDetails.accountNumberstringNoUSD_DEPOSIT_ACCOUNT and NGN_DEPOSIT_ACCOUNT.
destination.bankAccountDetails.bankAccountTypeenumNoWhich fields are populated. The NGN, UGX and KES types populate accountHolderName, accountNumber and bankName. A GB deposit populates those fields too and carries no type.
USD_DEPOSIT_ACCOUNTEUR_DEPOSIT_ACCOUNTMXN_SPEI_DEPOSIT_ACCOUNTNGN_DEPOSIT_ACCOUNTUGX_DEPOSIT_ACCOUNTKES_DEPOSIT_ACCOUNTBRL_PIX_DEPOSIT_ACCOUNTCOP_BRE_B_DEPOSIT_ACCOUNT
destination.bankAccountDetails.bankNamestringNoNGN_DEPOSIT_ACCOUNT. The bank holding the account, which the payer needs.
destination.bankAccountDetails.bicstringNoEUR_DEPOSIT_ACCOUNT.
destination.bankAccountDetails.breBKeystringNoCOP_BRE_B_DEPOSIT_ACCOUNT. The Bre-B key the customer pays to.
destination.bankAccountDetails.clabestringNoMXN_SPEI_DEPOSIT_ACCOUNT.
destination.bankAccountDetails.depositMessagestringNoA reference the payer must include, where the corridor requires one.
destination.bankAccountDetails.ibanstringNoEUR_DEPOSIT_ACCOUNT.
destination.bankAccountDetails.idstring (uuid)No
destination.bankAccountDetails.pixCopiaEColastringNoBRL_PIX_DEPOSIT_ACCOUNT. The EMV BR Code to display.
destination.bankAccountDetails.routingNumberstringNoUSD_DEPOSIT_ACCOUNT.
destination.currencystringYesISO 4217 code of the funds on this side. A deposit is quoted in the customer's local currency on the source side (NGN for a Nigerian deposit); every other transfer in USD. Send USD on a side the Flyra wallet is on, even though its balance reads USDB.
destination.idstring (uuid)No
destination.paymentInstrumentIdstring (uuid)ConditionalAn instrument Flyra manages; required unless type is sent. Not a virtual account (OWNED_VIRTUAL_BANK_ACCOUNT), which only receives money: use the wallet. Source and destination must be different instruments. Either mistake is refused with 422 VALIDATION_FAILED.
destination.typeenumNoSent instead of paymentInstrumentId for a side Flyra does not hold. CUSTOMER_EXTERNAL_BANK_ACCOUNT and CUSTOMER_EXTERNAL_CRYPTO_ACCOUNT are any bank or crypto account the customer owns. PROVIDED_BANK_ACCOUNT is a one-time account Flyra creates to accept a deposit; its details come back in bankAccountDetails.
CUSTOMER_EXTERNAL_BANK_ACCOUNTCUSTOMER_EXTERNAL_CRYPTO_ACCOUNTPROVIDED_BANK_ACCOUNT
disclaimerstringRead-onlyText to show the customer, where the corridor requires one.
expiresAtintegerRead-onlyWhen the deposit instructions stop being valid, as Unix epoch milliseconds UTC. Present only while a deposit is outstanding.
expiresInobjectRead-onlyHow long the deposit instructions stay valid, as a value and unit. Show this rather than computing it from expiresAt.
expiresIn.unitstringRead-only
expiresIn.valueintegerRead-only
feesobjectRead-only
fees.amountstringRead-onlyDecimal string.
fees.currencystringRead-only
idstring (uuid)Read-only
ratenumberRead-onlyThe rate Flyra applied between the two sides. Present on a converting transfer only.
sourceobjectYesOne end of the transfer, with its own currency and amount, so a transfer can change currency. Identify it by paymentInstrumentId or by type, not both. instrumentType and country are not accepted.
source.amountstringNoDecimal string in this side's currency. Send it on the source only: Flyra prices the transfer from it and fills in the destination amount, which is ignored on a request.
source.bankAccountDetailsobjectNoReturned when this side's type is PROVIDED_BANK_ACCOUNT: where the customer pays in to complete the deposit. The fields present follow bankAccountType. The transfer stays PENDING until the customer pays.
source.bankAccountDetails.accountHolderNamestringNoEvery type.
source.bankAccountDetails.accountNumberstringNoUSD_DEPOSIT_ACCOUNT and NGN_DEPOSIT_ACCOUNT.
source.bankAccountDetails.bankAccountTypeenumNoWhich fields are populated. The NGN, UGX and KES types populate accountHolderName, accountNumber and bankName. A GB deposit populates those fields too and carries no type.
USD_DEPOSIT_ACCOUNTEUR_DEPOSIT_ACCOUNTMXN_SPEI_DEPOSIT_ACCOUNTNGN_DEPOSIT_ACCOUNTUGX_DEPOSIT_ACCOUNTKES_DEPOSIT_ACCOUNTBRL_PIX_DEPOSIT_ACCOUNTCOP_BRE_B_DEPOSIT_ACCOUNT
source.bankAccountDetails.bankNamestringNoNGN_DEPOSIT_ACCOUNT. The bank holding the account, which the payer needs.
source.bankAccountDetails.bicstringNoEUR_DEPOSIT_ACCOUNT.
source.bankAccountDetails.breBKeystringNoCOP_BRE_B_DEPOSIT_ACCOUNT. The Bre-B key the customer pays to.
source.bankAccountDetails.clabestringNoMXN_SPEI_DEPOSIT_ACCOUNT.
source.bankAccountDetails.depositMessagestringNoA reference the payer must include, where the corridor requires one.
source.bankAccountDetails.ibanstringNoEUR_DEPOSIT_ACCOUNT.
source.bankAccountDetails.idstring (uuid)No
source.bankAccountDetails.pixCopiaEColastringNoBRL_PIX_DEPOSIT_ACCOUNT. The EMV BR Code to display.
source.bankAccountDetails.routingNumberstringNoUSD_DEPOSIT_ACCOUNT.
source.currencystringYesISO 4217 code of the funds on this side. A deposit is quoted in the customer's local currency on the source side (NGN for a Nigerian deposit); every other transfer in USD. Send USD on a side the Flyra wallet is on, even though its balance reads USDB.
source.idstring (uuid)No
source.paymentInstrumentIdstring (uuid)ConditionalAn instrument Flyra manages; required unless type is sent. Not a virtual account (OWNED_VIRTUAL_BANK_ACCOUNT), which only receives money: use the wallet. Source and destination must be different instruments. Either mistake is refused with 422 VALIDATION_FAILED.
source.typeenumNoSent instead of paymentInstrumentId for a side Flyra does not hold. CUSTOMER_EXTERNAL_BANK_ACCOUNT and CUSTOMER_EXTERNAL_CRYPTO_ACCOUNT are any bank or crypto account the customer owns. PROVIDED_BANK_ACCOUNT is a one-time account Flyra creates to accept a deposit; its details come back in bankAccountDetails.
CUSTOMER_EXTERNAL_BANK_ACCOUNTCUSTOMER_EXTERNAL_CRYPTO_ACCOUNTPROVIDED_BANK_ACCOUNT
statusenumRead-onlyA transfer Flyra is still processing is reported as PENDING.
PENDINGPOSTEDSETTLEDREFUNDEDFAILED
updatedTimestring (date-time)Read-onlyWhen the transfer last changed. ISO 8601, UTC. Compare it across webhook deliveries to discard an event that arrived out of order.
bankAccountTypeFields in bankAccountDetails (all read-only)
USD_DEPOSIT_ACCOUNTaccountHolderName, accountNumber, routingNumber
EUR_DEPOSIT_ACCOUNTaccountHolderName, iban, bic
MXN_SPEI_DEPOSIT_ACCOUNTaccountHolderName, clabe
NGN_DEPOSIT_ACCOUNT, UGX_DEPOSIT_ACCOUNT, KES_DEPOSIT_ACCOUNTaccountHolderName, accountNumber, bankName
BRL_PIX_DEPOSIT_ACCOUNTaccountHolderName, pixCopiaECola
COP_BRE_B_DEPOSIT_ACCOUNTaccountHolderName, breBKey

Every type also returns id and bankAccountType, and depositMessage where the corridor needs a reference the payer must include.

3 · Authentication

Authenticating API calls

Every call except the token request carries a short-lived access token. You get it by exchanging the client ID and secret of one of your API credentials at POST /v1/oauth2/token. This is the standard OAuth 2.0 client credentials grant (RFC 6749, section 4.4), so any OAuth 2.0 client library works.

  1. Create API credentials. On the API credentials page of the Partner Dashboard, with only the scopes the system needs. Use separate credentials for separate systems, so you can revoke one without stopping the others.
  2. Request an access token. Send grant_type=client_credentials, client_id and client_secret form-encoded, or the ID and secret with HTTP Basic authentication; if you send both, the header wins. Add scope to limit the token to some of the credential's scopes.
  3. Call the API with the token. Send Authorization: Bearer <access_token> on every request.
  4. Reuse the token until it expires. expires_in is its lifetime in seconds (five minutes in the sandbox). Request a new one shortly before it expires; there is no refresh token. Don't request a new token for every call.
The client secret belongs on your server only: never ship it in a mobile app or a web page. Treat the token like a password: never log it, store it in a database or put it in a URL.
1 · Request an access token
curl -X POST "https://api.flyra.com/v1/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id="$FLYRA_CLIENT_ID" \
  --data-urlencode client_secret="$FLYRA_CLIENT_SECRET" \
  --data-urlencode scope="customers:read transfers:read"
Token response
HTTP/1.1 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "customers:read transfers:read"
}
2 · Call the API with the token
curl -X GET "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Token error
HTTP/1.1 401 Unauthorized

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

Token errors

The token endpoint answers errors in the OAuth 2.0 format, {"error": …, "error_description": …}, not the error array the rest of the API uses.

StatuserrorWhat to do
400invalid_requestThe body is malformed or a field is missing. Fix the request.
400unsupported_grant_typeSend grant_type=client_credentials.
400invalid_scopeYour credential is valid, but you asked for a scope it does not have. Ask for fewer scopes, or add the scope to the credential in the Partner Dashboard.
401invalid_clientThe credential cannot be used: unknown client ID, wrong secret, revoked or expired credential, or an inactive organization. A 401 never says which; check the client ID and the environment before rotating a secret that works elsewhere.
415The body is not form-encoded (for example, JSON). This one answers in the API's error array.
503Flyra could not check the credential right now. Retry with backoff. Answers in the API's error array.

Scopes

Each endpoint needs exactly one scope, shown on its card in the API reference. A token without it gets 403.

ScopeAllows
customers:readRead customers, related parties and documents.
customers:writeCreate and update customers, related parties and documents.
kyc:readRead KYC verifications.
kyc:writeStart KYC verifications.
accounts:readRead accounts and balances.
accounts:writeOpen virtual accounts for customers.
payment_instruments:readRead payment instruments and look up bank networks.
payment_instruments:writeCreate payment instruments. No endpoint needs it yet.
transfers:readRead and list transfers, and quote rates.
transfers:writeCreate transfers.
4 · Basic workflow · Business

From new Business to first transfer

The calls a typical integration makes for one business customer, such as a payment service provider's merchant, once it has a token. Steps run in order: payment instruments can only be created once the business is KYC approved. Every POST needs an X-Idempotency-Key.

Onboard

Steps 1–4
  1. 1

    Create the business

    Create a customer of type BUSINESS. Keep the returned id, and send your own id as internalCustomerId to match it back later.

  2. 2

    Create the individuals

    Create a customer of type INDIVIDUAL for each person behind the business: owners, directors, signers.

  3. 3

    Link related parties

    Link each person to the business with their roles.

  4. 4

    Add documents and due diligence

    Add the documents verification needs, and answer the due-diligence questions.

Verify

Steps 5–6
  1. 5

    Start KYC verification

    Submit the business for verification. It starts as PENDING.

  2. 6

    Follow the result

    Receive events, or poll, until the verification is APPROVED or DECLINED.

On approval, Flyra gives the business a wallet: an OWNED_WALLET_ACCOUNT payment instrument, held in a FLYRA_WALLET account.

Transact

Steps 7–10
  1. 7

    Add money

    Create a deposit into the wallet with a PROVIDED_BANK_ACCOUNT source; source.bankAccountDetails say where the customer pays in. Deposits in Nigeria, Kenya and Uganda need the customer's nationalIdentifiers for that country. In the sandbox, see Add test money.

  2. 8

    Create payment instruments

    Open a virtual account with OWNED_VIRTUAL_BANK_ACCOUNT, or link a payout account with LINKED_BANK_ACCOUNT or LINKED_MOBILE_MONEY_ACCOUNT. A virtual account's setup fee may be due from the wallet up front, which is why the deposit comes first. In Nigeria, Kenya, Uganda and South Africa, look up the network first.

  3. 9

    Quote a rate

    Show the customer the indicative rate. You send no rate with the transfer: Flyra prices it when it runs.

  4. 10

    Create the transfer

    It starts PENDING. Follow it until it reaches SETTLED or FAILED.

4 · Basic workflow · Individual

From new individual customer to first transfer

Individual customers go through the same three phases with fewer steps: there are no related parties. Payment instruments can only be created once the individual is KYC approved.

Onboard

Steps 1–2
  1. 1

    Create the customer

    Create a customer of type INDIVIDUAL with their name, contacts, residential address, identifiers, residence and citizenship, and termsAcceptedAt.

  2. 2

    Add documents and due diligence

    Add identity documents, and answer the due-diligence questions.

Verify

Steps 3–4
  1. 3

    Start KYC verification

    Submit the individual for verification. It starts as PENDING.

  2. 4

    Follow the result

    Receive events, or poll, until the verification is APPROVED or DECLINED.

On approval, Flyra gives the individual a wallet: an OWNED_WALLET_ACCOUNT payment instrument, held in a FLYRA_WALLET account.

Transact

Steps 5–8
  1. 5

    Add money

    Create a deposit into the wallet with a PROVIDED_BANK_ACCOUNT source; source.bankAccountDetails say where the customer pays in. Deposits in Nigeria, Kenya and Uganda need the customer's nationalIdentifiers for that country. In the sandbox, see Add test money.

  2. 6

    Create payment instruments

    Open a virtual account with OWNED_VIRTUAL_BANK_ACCOUNT, or link a payout account with LINKED_BANK_ACCOUNT or LINKED_MOBILE_MONEY_ACCOUNT. A virtual account's setup fee may be due from the wallet up front, which is why the deposit comes first. In Nigeria, Kenya, Uganda and South Africa, look up the network first.

  3. 7

    Quote a rate

    Show the customer the indicative rate. You send no rate with the transfer: Flyra prices it when it runs.

  4. 8

    Create the transfer

    It starts PENDING. Follow it until it reaches SETTLED or FAILED.

4 · Use case

Remittances for employees

A classic reason for an organization to use Flyra for individual customers is to let its employees send money home. The organization onboards each employee once, funds their wallet, and pays out to an account the employee holds in their home country, on the employee's behalf.

  1. a

    Onboard and verify the employee

    Create the employee as a customer of type INDIVIDUAL, answer the due-diligence questions, then start their KYC verification and wait for APPROVED. Keep your employee number in internalCustomerId.

  2. b

    Fund the wallet

    Deposit into the employee's OWNED_WALLET_ACCOUNT, for example with a PROVIDED_BANK_ACCOUNT source the employee pays into.

  3. c

    Link the destination account

    Look up the bank's network for the country, then create a LINKED_BANK_ACCOUNT with the account number, bankCode and the name the account is held in. In Kenya and Uganda, a LINKED_MOBILE_MONEY_ACCOUNT works the same way.

  4. d

    Quote and pay out

    Show the employee the rate for SEND_TO_BANK, then create a transfer from the wallet to the linked account, with the amount on the source side.

Every POST needs its own X-Idempotency-Key, so a retried payout never sends money twice. Retry a timed-out payout with the same key, never a new one.
a · Create the employee
curl -X POST "https://api.flyra.com/v1/customers" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: d94d7fdc-f41c-4ed8-9625-6bbeb51f55bf" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "INDIVIDUAL",
  "internalCustomerId": "EMP-20931",
  "name": {
    "firstName": "Amara",
    "lastName": "Okafor"
  },
  "emailAddress": [
    {
      "type": "PERSONAL",
      "email": "amara.okafor@example.com"
    }
  ],
  "phoneNumber": [
    {
      "type": "PERSONAL",
      "number": "+14155550142"
    }
  ],
  "dateOfBirth": "1990-04-12",
  "residentialAddress": {
    "type": "RESIDENTIAL",
    "addressLine1": "2150 Mission St",
    "addressLine2": "Apt 4",
    "city": "San Francisco",
    "postalCode": "94110",
    "state": "CA",
    "country": "US"
  },
  "countryOfResidence": "US",
  "citizenships": [
    {
      "country": "NG"
    }
  ],
  "nationalIdentifiers": [
    {
      "type": "PASSPORT",
      "nationalId": "A08291037",
      "issuingCountry": "NG",
      "expiryDate": "2031-03-14"
    }
  ],
  "termsAcceptedAt": "2026-01-15T09:30:00Z"
}'
c · Link the destination account
curl -X POST "https://api.flyra.com/v1/customers/83c9e5db-8f89-497f-ba6d-d33e22266a0b/payment-instruments" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: c34457d6-ba0f-4478-aa90-28a20d9604ae" \
  -H "Content-Type: application/json" \
  -d '{
  "instrumentType": "LINKED_BANK_ACCOUNT",
  "country": "NG",
  "currency": "NGN",
  "accountNumber": "0123455678",
  "bankCode": "6df48502-1ebe-473f-be17-e2cae4dd67ee",
  "bankName": "Example Bank Nigeria",
  "accountName": "Amara Okafor",
  "nickName": "Lagos savings"
}'
d · Quote the rate
curl -X GET "https://api.flyra.com/v1/rates?customerId=83c9e5db-8f89-497f-ba6d-d33e22266a0b&sourceCountry=US&destinationCountry=NG&flow=SEND_TO_BANK" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
d · Pay out
curl -X POST "https://api.flyra.com/v1/transfers" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: bea235b2-a0ab-46ac-bcc1-8536cfc647f1" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "83c9e5db-8f89-497f-ba6d-d33e22266a0b",
  "source": {
    "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e",
    "currency": "USD",
    "amount": "400.00"
  },
  "destination": {
    "paymentInstrumentId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "currency": "NGN"
  }
}'
Conventions

Conventions & errors

These rules apply to every endpoint in this reference.

JSON over HTTPS

Request and response bodies are JSON in UTF-8, with camelCase field names. The token endpoint is the one exception: form-encoded in and snake_case out, as OAuth 2.0 requires.

Ids

Ids are UUIDs generated by Flyra. Treat them as opaque strings.

Dates and times

Dates use YYYY-MM-DD. Timestamps use ISO 8601 in UTC, for example 2026-01-15T09:30:00Z.

Amounts

Amounts are decimal strings, for example "250.00", so no precision is lost.

Countries and currencies

Countries are ISO 3166-1 alpha-2 codes (US, NG); currencies are ISO 4217 codes (USD, NGN).

Updates

PATCH changes only the fields you send. An array you send replaces the stored one completely, so read the resource first to add to a list.

Your own data only

You only see your organization's resources. Another organization's id answers 404, exactly like an id that does not exist.

Compatibility

Version 1 only changes in backward-compatible ways: new endpoints, new optional fields, and new values in lists such as statuses. Ignore fields and values you do not know. A breaking change would come as /v2.

Errors

Use the HTTP status to decide what to do, and the body to tell your team or your customer what went wrong. Every error except the token endpoint's is a JSON array of one or more problems, even when there is only one. A validation failure lists one entry per field, so read the whole array. New name values may appear at any time; handle a name you do not know by its status.

FieldAlways presentMeaning
codeYesThe HTTP status, as a string.
messageYesA readable description in English. Show it to your team, not to end customers, and do not parse it.
nameNoA short name for the problem, such as CUSTOMER_REQUEST_INVALID or IDEMPOTENT_REQUEST_IN_FLIGHT, or the field that failed validation.
pathNoThe request path.
timestampNoWhen the error happened, in UTC, without a time zone suffix.
resourceTypeNoThe type of resource the problem concerns, when there is one.
resourceIdNoThe id of that resource.
Error response
HTTP/1.1 422 Unprocessable Entity

[
  {
    "code": "422",
    "name": "CUSTOMER_REQUEST_INVALID",
    "message": "legalName is required for a BUSINESS customer.",
    "path": "/v1/customers",
    "timestamp": "2026-10-13T09:15:04.123"
  }
]
HTTP statusMeaningRetry?
400 Bad RequestThe request is malformed: invalid JSON, a bad parameter, or an X-Idempotency-Key that is missing on a POST or too long (IDEMPOTENCY_KEY_TOO_LONG).No. Fix the request.
401 UnauthorizedThe access token is missing, invalid or expired.Get a new token, then retry once.
403 ForbiddenThe token lacks the endpoint's scope, or your organization cannot use this endpoint (for example, while it is suspended).No. Add the scope to the credential.
404 Not FoundThe resource does not exist, or belongs to another organization.No.
409 ConflictThe request conflicts with the resource's current state. With IDEMPOTENT_REQUEST_IN_FLIGHT, an earlier request with the same idempotency key has no outcome yet. With IDEMPOTENCY_KEY_REUSED, the key was used for a different request.Only for IDEMPOTENT_REQUEST_IN_FLIGHT: retry the same request with the same key after a short wait.
422 Unprocessable EntityThe request is well formed but breaks a business rule, such as a field a customer type does not allow. Each error's name says which rule or field.No. Fix the data.
429 Too Many RequestsToo many requests.Yes, after the number of seconds in the Retry-After header.
500 Internal Server ErrorSomething failed on Flyra's side.Yes, with backoff and the same idempotency key.
503 Service UnavailableA service Flyra depends on is unavailable.Yes, with backoff and the same idempotency key.

Retry with exponential backoff (for example 1, 2, 4, 8 seconds, plus a little randomness) and give up after a few attempts. Always resend a POST with the same X-Idempotency-Key. After a 500 or 503 on a POST, the same key can answer 409 IDEMPOTENT_REQUEST_IN_FLIGHT for about five minutes: keep the key and retry after that.

Idempotent requests

A network timeout leaves you not knowing whether a create succeeded. Every POST except the token request requires an X-Idempotency-Key header, so a retry is safe: once a request has succeeded, every retry with its key gets the first response and nothing is created again.

  1. Use a new key for every new operation. A random UUID v4, at most 100 characters. A counter or an order number can repeat, so do not use one. Keys belong to your organization.
  2. Store the key before you send. Keep it with your own record, so a retry after a crash reuses it.
  3. Retry with the same key and request. If the first attempt succeeded, you get its response again, unchanged. A key is kept for 30 days.
  4. Never send a new key to retry. To Flyra it is a different request, and for a transfer it can move money twice.
The first request with this keyA retry with the same key and request
SucceededThe first response again, unchanged.
Is still running, or ended without an outcome409 IDEMPOTENT_REQUEST_IN_FLIGHT: “not yet”, not “failed”. Retry with the same key. A request that ended without an outcome (it died, timed out or answered a 5xx) answers this for about five minutes; then the next retry runs the request again.
Was refused with a 4xxThe request runs again, so you can correct it and resend with the same key.
A POST without the header is refused with 400 MISSING_IDEMPOTENCY_KEY; a key over 100 characters with 400 IDEMPOTENCY_KEY_TOO_LONG. The same key with a different request, or on a different endpoint, is refused with 409 IDEMPOTENCY_KEY_REUSED.
A customer create refused after the customer was made, for an identifier document for example, keeps that customer under its key. The same request, or one with corrected identifier documents, carries on with that customer; a request that changes anything else is refused with 409 IDEMPOTENCY_KEY_REUSED. PATCH, GET and DELETE take no key: repeating them has no further effect.
Retrying a transfer with the same key
# Attempt 1 times out. Attempt 2 sends the identical request and key.
curl -X POST "https://api.flyra.com/v1/transfers" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: 3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "source": {
    "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e",
    "currency": "USD",
    "amount": "250.00"
  },
  "destination": {
    "paymentInstrumentId": "6f1e2d3c-4b5a-4c69-8d7e-0f1a2b3c4d5e",
    "currency": "USD"
  }
}'
Answer while the first attempt has no outcome
HTTP/1.1 409 Conflict

[
  {
    "code": "409",
    "name": "IDEMPOTENT_REQUEST_IN_FLIGHT",
    "message": "A request with this idempotency key has no outcome yet. Retry with the same key."
  }
]

Request IDs

Send an X-Request-Id header with a unique value (a UUID works) on every call and log it with your own record. Use 1 to 128 letters, digits, ., _, : or -; any other value, or none, is replaced by one Flyra generates. The response's X-Request-Id header always carries the id used. When you contact support about a call, quote its request id, the time and the endpoint.

5 · API reference

Core APIs

All paths are relative to the environment's base URL; the examples use https://api.flyra.com. Path parameters are shown in {braces}. The examples follow one business, Andes Trade Partners LLC, so ids carry over from one call to the next.

Access tokens

How your system gets the token every other call needs. See Authentication.

POST

Request an access token

/v1/oauth2/token

Exchanges the client ID and secret of an API credential for a bearer token (OAuth 2.0 client credentials grant). The body is form-encoded and the response is snake_case, as OAuth 2.0 requires. You can send the client ID and secret with HTTP Basic instead of form fields; if you send both, the header wins.

No token needed: this call authenticates with the client ID and secret.

Request body

Form-encoded (application/x-www-form-urlencoded).

grant_typestringRequired Always client_credentials.
client_idstringThe client ID of your API credential. Required unless you use HTTP Basic.
client_secretstringIts client secret. Required unless you use HTTP Basic.
scopestringOptional Space-separated scopes to limit the token to. Leave it out to get every scope the credential has.

Response

200 A token was issued.

access_tokenstringThe bearer token. Treat it like a password: never log it or put it in a URL.
token_typestringAlways Bearer.
expires_inintegerSeconds until the token expires (300 in the sandbox). There is no refresh token.
scopestringSpace-separated scopes the token carries.

Error codes: invalid_request, invalid_client, invalid_grant, invalid_scope, unsupported_grant_type. Token errors use the OAuth 2.0 format; see Token errors.

Errors: 400, 401, 503. See Errors.

Request
curl -X POST "https://api.flyra.com/v1/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id="$FLYRA_CLIENT_ID" \
  --data-urlencode client_secret="$FLYRA_CLIENT_SECRET"
Response
HTTP/1.1 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbmRlcy10cmFkZSJ9.c2lnbmF0dXJl",
  "expires_in": 300,
  "scope": "customers:read customers:write transfers:read transfers:write",
  "token_type": "Bearer"
}

Customers

Business and individual customers. Both use the same endpoints; the type field selects the shape. See the Customer model.

POST

Create a customer

/v1/customers

Creates a customer of type BUSINESS or INDIVIDUAL. For a business, create the business first, then one INDIVIDUAL customer for every person you will link as a related party. A BUSINESS requires legalStructure and rejects name; an INDIVIDUAL requires name and rejects legalStructure. A request breaking a rule is refused with 422 CUSTOMER_REQUEST_INVALID before anything is created.

Scope customers:write

Headers

X-Idempotency-KeystringRequired A unique key for this request, at most 100 characters, such as a UUID v4. A retry with the same key returns the first response instead of repeating the request. How idempotency works.

Request body

The Customer object without read-only fields.

Response

201 The customer was created. Returns the Customer.

Errors: 400, 401, 403, 409, 422, 500. See Errors.

Request · business
curl -X POST "https://api.flyra.com/v1/customers" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: 3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "BUSINESS",
  "countryOfRegistration": "US",
  "doingBusinessAs": "Andes Trade",
  "emailAddress": [
    {
      "type": "BUSINESS",
      "email": "finance@andestrade.example.com"
    }
  ],
  "incorporatedAt": "2019-04-02",
  "internalCustomerId": "acct-10042",
  "legalName": "Andes Trade Partners LLC",
  "legalStructure": "LIMITED_LIABILITY_COMPANY",
  "phoneNumber": [
    {
      "type": "BUSINESS",
      "number": "+14155550100"
    }
  ],
  "registeredAddress": {
    "type": "BUSINESS_REGISTERED",
    "addressLine1": "100 Market Street",
    "addressLine2": "Suite 300",
    "city": "San Francisco",
    "country": "US",
    "postalCode": "94105",
    "state": "CA"
  },
  "taxIdentifiers": [
    {
      "type": "EIN",
      "issuingCountry": "US",
      "taxId": "12-3456789"
    }
  ],
  "termsAcceptedAt": "2026-01-15T09:30:00Z",
  "website": "https://andestrade.example.com"
}'
Response · business
HTTP/1.1 201 Created

{
  "id": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "type": "BUSINESS",
  "countryOfRegistration": "US",
  "doingBusinessAs": "Andes Trade",
  "emailAddress": [
    {
      "id": "0afce7c7-5c9d-4913-b21a-882cf6e2dd11",
      "type": "BUSINESS",
      "email": "finance@andestrade.example.com"
    }
  ],
  "incorporatedAt": "2019-04-02",
  "internalCustomerId": "acct-10042",
  "legalName": "Andes Trade Partners LLC",
  "legalStructure": "LIMITED_LIABILITY_COMPANY",
  "phoneNumber": [
    {
      "id": "57a3a6e2-7391-444d-9e42-94a76254da1d",
      "type": "BUSINESS",
      "number": "+14155550100"
    }
  ],
  "registeredAddress": {
    "id": "6622d2cb-25ad-4229-8e4e-ee9a01ed71cf",
    "type": "BUSINESS_REGISTERED",
    "addressLine1": "100 Market Street",
    "addressLine2": "Suite 300",
    "city": "San Francisco",
    "country": "US",
    "postalCode": "94105",
    "state": "CA"
  },
  "taxIdentifiers": [
    {
      "id": "f3859de8-7f5f-4915-8876-e6b18515b691",
      "type": "EIN",
      "issuingCountry": "US",
      "taxId": "12-3456789"
    }
  ],
  "termsAcceptedAt": "2026-01-15T09:30:00Z",
  "website": "https://andestrade.example.com"
}
Request · individual
curl -X POST "https://api.flyra.com/v1/customers" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: b6a1e0c2-4f3d-4c8e-9a71-2d5f8e3b0c94" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "INDIVIDUAL",
  "citizenships": [
    {
      "country": "NG"
    }
  ],
  "countryOfResidence": "NG",
  "dateOfBirth": "1990-04-12",
  "emailAddress": [
    {
      "type": "PERSONAL",
      "email": "amara.okafor@example.com"
    }
  ],
  "internalCustomerId": "user-20017",
  "name": {
    "firstName": "Amara",
    "lastName": "Okafor"
  },
  "nationalIdentifiers": [
    {
      "type": "BVN",
      "issuingCountry": "NG",
      "nationalId": "22212345678"
    },
    {
      "type": "NIN",
      "issuingCountry": "NG",
      "nationalId": "12345678901"
    }
  ],
  "phoneNumber": [
    {
      "type": "PERSONAL",
      "number": "+2348012345678"
    }
  ],
  "residentialAddress": {
    "type": "RESIDENTIAL",
    "addressLine1": "12 Admiralty Way",
    "city": "Lagos",
    "country": "NG",
    "postalCode": "106104",
    "state": "Lagos"
  },
  "termsAcceptedAt": "2026-01-15T09:30:00Z"
}'
Response · individual
HTTP/1.1 201 Created

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "INDIVIDUAL",
  "citizenships": [
    {
      "id": "46b3f0c7-ee11-4aff-9a63-658c85ac1ea3",
      "country": "NG"
    }
  ],
  "countryOfResidence": "NG",
  "dateOfBirth": "1990-04-12",
  "emailAddress": [
    {
      "id": "86c77485-50fd-4f42-9829-909693ada444",
      "type": "PERSONAL",
      "email": "amara.okafor@example.com"
    }
  ],
  "internalCustomerId": "user-20017",
  "name": {
    "firstName": "Amara",
    "lastName": "Okafor"
  },
  "nationalIdentifiers": [
    {
      "id": "953483f7-4c39-4ab1-b8a2-4be61c6803d2",
      "type": "BVN",
      "issuingCountry": "NG",
      "nationalId": "22212345678"
    },
    {
      "id": "f5112ac8-03a8-4a78-a070-824af12bf0b2",
      "type": "NIN",
      "issuingCountry": "NG",
      "nationalId": "12345678901"
    }
  ],
  "phoneNumber": [
    {
      "id": "46e5105b-db09-4d33-a56b-a28d9a501ca8",
      "type": "PERSONAL",
      "number": "+2348012345678"
    }
  ],
  "residentialAddress": {
    "id": "d2bdd5cf-e762-4abc-ac8e-1198ff6db359",
    "type": "RESIDENTIAL",
    "addressLine1": "12 Admiralty Way",
    "city": "Lagos",
    "country": "NG",
    "postalCode": "106104",
    "state": "Lagos"
  },
  "termsAcceptedAt": "2026-01-15T09:30:00Z"
}
GET

Read a customer

/v1/customers/{customerId}

The customer as Flyra holds it, including the ids generated for its addresses, contacts and identifiers.

Scope customers:read

Path parameters

customerIdstring (uuid)Id of the customer.

Response

200 The customer. Returns the Customer.

Errors: 401, 403, 404, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "id": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "type": "BUSINESS",
  "countryOfRegistration": "US",
  "doingBusinessAs": "Andes Trade",
  "emailAddress": [
    {
      "id": "0afce7c7-5c9d-4913-b21a-882cf6e2dd11",
      "type": "BUSINESS",
      "email": "finance@andestrade.example.com"
    }
  ],
  "incorporatedAt": "2019-04-02",
  "internalCustomerId": "acct-10042",
  "legalName": "Andes Trade Partners LLC",
  "legalStructure": "LIMITED_LIABILITY_COMPANY",
  "phoneNumber": [
    {
      "id": "57a3a6e2-7391-444d-9e42-94a76254da1d",
      "type": "BUSINESS",
      "number": "+14155550100"
    }
  ],
  "registeredAddress": {
    "id": "6622d2cb-25ad-4229-8e4e-ee9a01ed71cf",
    "type": "BUSINESS_REGISTERED",
    "addressLine1": "100 Market Street",
    "addressLine2": "Suite 300",
    "city": "San Francisco",
    "country": "US",
    "postalCode": "94105",
    "state": "CA"
  },
  "taxIdentifiers": [
    {
      "id": "f3859de8-7f5f-4915-8876-e6b18515b691",
      "type": "EIN",
      "issuingCountry": "US",
      "taxId": "12-3456789"
    }
  ],
  "termsAcceptedAt": "2026-01-15T09:30:00Z",
  "website": "https://andestrade.example.com"
}
PATCH

Update a customer

/v1/customers/{customerId}

Changes only the fields you send. An array you send replaces the stored one completely (sending one email address removes the others), so read the customer first to add to a list. type cannot be changed, and the rules of Create a customer still apply to what you send.

Scope customers:write

Path parameters

customerIdstring (uuid)Id of the customer.

Request body

Any writable field of the Customer object except type. A list you send must keep at least one email address and one phone number.

Response

200 The customer as it now stands. Returns the Customer.

Errors: 400, 401, 403, 404, 422, 500. See Errors.

Request
curl -X PATCH "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "emailAddress": [
    {
      "type": "BUSINESS",
      "email": "treasury@andestrade.example.com"
    }
  ]
}'
Response
HTTP/1.1 200 OK

{
  "id": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "type": "BUSINESS",
  "countryOfRegistration": "US",
  "doingBusinessAs": "Andes Trade",
  "emailAddress": [
    {
      "id": "275bb5e9-45fc-4043-91de-d6cbd8e40dd3",
      "type": "BUSINESS",
      "email": "treasury@andestrade.example.com"
    }
  ],
  "incorporatedAt": "2019-04-02",
  "internalCustomerId": "acct-10042",
  "legalName": "Andes Trade Partners LLC",
  "legalStructure": "LIMITED_LIABILITY_COMPANY",
  "phoneNumber": [
    {
      "id": "57a3a6e2-7391-444d-9e42-94a76254da1d",
      "type": "BUSINESS",
      "number": "+14155550100"
    }
  ],
  "registeredAddress": {
    "id": "6622d2cb-25ad-4229-8e4e-ee9a01ed71cf",
    "type": "BUSINESS_REGISTERED",
    "addressLine1": "100 Market Street",
    "addressLine2": "Suite 300",
    "city": "San Francisco",
    "country": "US",
    "postalCode": "94105",
    "state": "CA"
  },
  "taxIdentifiers": [
    {
      "id": "f3859de8-7f5f-4915-8876-e6b18515b691",
      "type": "EIN",
      "issuingCountry": "US",
      "taxId": "12-3456789"
    }
  ],
  "termsAcceptedAt": "2026-01-15T09:30:00Z",
  "website": "https://andestrade.example.com"
}

Documents

Files verification needs, for a business and its people or for an individual customer. See the Document model.

POST

Add a document

/v1/customers/{customerId}/documents

Adds a business or profile record (proof of address, formation and ownership documents, a profile picture) or an identity document. Verification only reads an identity document once it is linked: put the returned id on the matching nationalIdentifiers entry as documentId, with Create or Update a customer.

Scope customers:write

Headers

X-Idempotency-KeystringRequired A unique key for this request, at most 100 characters, such as a UUID v4. A retry with the same key returns the first response instead of repeating the request. How idempotency works.

Path parameters

customerIdstring (uuid)Id of the customer.

Response

201 The document was added. Returns the Document.

Errors: 400, 401, 403, 409, 422, 500. See Errors.

Request
curl -X POST "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/documents" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: c34457d6-ba0f-4478-aa90-28a20d9604ae" \
  -H "Content-Type: application/json" \
  -d '{
  "documentContent": "data:application/pdf;base64,JVBERi0xLjcK",
  "documentType": "PROOF_OF_ADDRESS",
  "name": "utility-bill-2026-01.pdf"
}'
Response
HTTP/1.1 201 Created

{
  "id": "f6e5d4c3-b2a1-4098-8765-43210fedcba9",
  "documentType": "PROOF_OF_ADDRESS",
  "name": "utility-bill-2026-01.pdf"
}

Request body

AttributeTypeRequiredDescription
documentContentstringYesThe file as a data URI, for example data:application/pdf;base64,JVBERi0xLjcK...
documentTypeenumYesBUSINESS_FORMATION, BUSINESS_OWNERSHIP and the other business values apply to BUSINESS customers only. The identity types, PASSPORT through SELFIE, belong to an INDIVIDUAL and are the photo behind a nationalIdentifiers entry.
PROFILE_PICTUREPROOF_OF_ADDRESSGOVERNMENT_IDPASSPORTSTATE_IDVOTER_IDNATIONAL_IDDRIVING_LICENSESELFIEBUSINESS_FORMATIONBUSINESS_OWNERSHIPFORMATION_DOCUMENTOWNERSHIP_DOCUMENTTAX_ID_DOCUMENTPROOF_OF_BUSINESS_ADDRESSPROOF_OF_BUSINESS_ACTIVITYOWNER_ID_PHOTOOTHER
namestringNoOriginal file name, kept for metadata only.

Due diligence

Answers about a customer's source of funds and the purpose of their account, which most customers need before KYC.

POST

Submit due-diligence answers

/v1/customers/{customerId}/due-diligence

Answers about where a customer's money comes from and what the account is for. Submitting again replaces the previous set. Required before KYC for most customers: for an INDIVIDUAL Flyra assesses as other than low risk (today a country list, plus anyone aged 60 or over), a verification started without it is refused; for a BUSINESS the verification is held open against each unanswered question. Fields marked INDIVIDUAL only or BUSINESS only are refused on the other type.

Scope customers:write

Headers

X-Idempotency-KeystringRequired A unique key for this request, at most 100 characters, such as a UUID v4. A retry with the same key returns the first response instead of repeating the request. How idempotency works.

Path parameters

customerIdstring (uuid)Id of the customer.

Response

201 The answers were recorded. Fields below.

Errors: 400, 401, 403, 404, 409, 422, 500. See Errors.

Request
curl -X POST "https://api.flyra.com/v1/customers/7c9e6679-7425-40de-944b-e07fc1f90ae7/due-diligence" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: bea235b2-a0ab-46ac-bcc1-8536cfc647f1" \
  -H "Content-Type: application/json" \
  -d '{
  "actingAsIntermediary": false,
  "employmentStatus": "employed",
  "occupation": "Software engineer",
  "purposeOfAccount": "Payments to Friends or Family Abroad",
  "sourceOfFunds": "salary",
  "transactionVolume": "0_4999"
}'
Response
HTTP/1.1 201 Created

{
  "actingAsIntermediary": false,
  "employmentStatus": "employed",
  "occupation": "Software engineer",
  "purposeOfAccount": "Payments to Friends or Family Abroad",
  "sourceOfFunds": "salary",
  "transactionVolume": "0_4999"
}

Request body

sourceOfFunds, employmentStatus, transactionVolume and estimatedAnnualRevenue take the verification provider's own values, passed through unchanged, for example sale_of_assets_real_estate or 50000_249999.

AttributeTypeRequiredDescription
actingAsIntermediarybooleanNoWhether the customer moves money on someone else's behalf.
complianceScreeningExplanationstringConditionalBUSINESS only. How the business screens the funds it moves. Required when conductsMoneyServices is true.
conductsMoneyServicesbooleanNoBUSINESS only. Whether the business transmits money for its own customers.
conductsMoneyServicesUsingBridgebooleanNoBUSINESS only. Whether that money moves through the customer's Flyra wallet.
employmentStatusstringNoINDIVIDUAL only.
estimatedAnnualRevenuestringNoBUSINESS only. Annual revenue band.
highRiskActivitiesarray of stringsNoBUSINESS only. Empty or absent means none apply.
highRiskActivitiesExplanationstringConditionalBUSINESS only. Required when highRiskActivities is not empty.
moneyServicesDescriptionstringConditionalBUSINESS only. Required when conductsMoneyServices is true.
occupationstringNoINDIVIDUAL only.
operatesInHighRiskGeographiesbooleanNoBUSINESS only. Whether the business operates in Cuba, Iran, Myanmar, North Korea or Syria.
otherPurposestringNoThe purpose in the customer's own words, when purposeOfAccount is an "other".
purposeOfAccountstringYesWhy the account exists, for example "Payments to Friends or Family Abroad".
regulatedByFinancialAuthoritybooleanNoBUSINESS only. Whether a financial regulator licenses the business.
sourceOfFundsstringYesWhere the money comes from, in the verification provider's values (for example salary). Required for both customer types.
sourceOfFundsDescriptionstringNoBUSINESS only. Where the money comes from, in the business's own words.
transactionVolumestringNoExpected monthly volume in USD, as a band, such as 0_4999, 50000_249999 or 1000000_plus.

Response body

AttributeTypePresentDescription
actingAsIntermediarybooleanWhen setWhether the customer moves money on someone else's behalf.
complianceScreeningExplanationstringWhen setBUSINESS only. How the business screens the funds it moves. Required when conductsMoneyServices is true.
conductsMoneyServicesbooleanWhen setBUSINESS only. Whether the business transmits money for its own customers.
conductsMoneyServicesUsingBridgebooleanWhen setBUSINESS only. Whether that money moves through the customer's Flyra wallet.
employmentStatusstringWhen setINDIVIDUAL only.
estimatedAnnualRevenuestringWhen setBUSINESS only. Annual revenue band.
highRiskActivitiesarray of stringsWhen setBUSINESS only. Empty or absent means none apply.
highRiskActivitiesExplanationstringWhen setBUSINESS only. Required when highRiskActivities is not empty.
moneyServicesDescriptionstringWhen setBUSINESS only. Required when conductsMoneyServices is true.
occupationstringWhen setINDIVIDUAL only.
operatesInHighRiskGeographiesbooleanWhen setBUSINESS only. Whether the business operates in Cuba, Iran, Myanmar, North Korea or Syria.
otherPurposestringWhen setThe purpose in the customer's own words, when purposeOfAccount is an "other".
purposeOfAccountstringAlwaysWhy the account exists, for example "Payments to Friends or Family Abroad".
regulatedByFinancialAuthoritybooleanWhen setBUSINESS only. Whether a financial regulator licenses the business.
sourceOfFundsstringAlwaysWhere the money comes from, in the verification provider's values (for example salary). Required for both customer types.
sourceOfFundsDescriptionstringWhen setBUSINESS only. Where the money comes from, in the business's own words.
transactionVolumestringWhen setExpected monthly volume in USD, as a band, such as 0_4999, 50000_249999 or 1000000_plus.

KYC verifications

Start a customer's verification and follow its status. See the KYC verification model.

POST

Start a KYC verification

/v1/customers/{customerId}/kyc-verifications

Submits the customer for verification. It starts PENDING; follow it with the list call or the customers.kyc_verifications.updated webhook. Takes no request body. The customer needs termsAcceptedAt and at least one national identifier first.

Scope kyc:write

Headers

X-Idempotency-KeystringRequired A unique key for this request, at most 100 characters, such as a UUID v4. A retry with the same key returns the first response instead of repeating the request. How idempotency works.

Path parameters

customerIdstring (uuid)Id of the customer.

Response

201 The verification was started. Returns the KYC verification.

Errors: 400, 401, 403, 404, 409, 500. See Errors.

Request
curl -X POST "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/kyc-verifications" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: 401f74ef-3581-4b67-a1f1-6e7af4f673f7"
Response
HTTP/1.1 201 Created

{
  "id": "b3c4d5e6-7f80-4a91-9b2c-3d4e5f6a7b8c",
  "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "status": "PENDING"
}
GET

List KYC verifications

/v1/customers/{customerId}/kyc-verifications

The customer's verifications, newest first, in data. Not paginated.

Scope kyc:read

Path parameters

customerIdstring (uuid)Id of the customer.

Response

200 The customer's verifications, newest first. Returns the KYC verification list in data.

Errors: 401, 403, 404, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/kyc-verifications" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "b3c4d5e6-7f80-4a91-9b2c-3d4e5f6a7b8c",
      "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
      "status": "APPROVED"
    }
  ]
}

Accounts

A customer's accounts with Flyra and the balances they hold. See the Account model.

GET

List accounts

/v1/customers/{customerId}/accounts

The customer's accounts, each with its balances, in data. A FLYRA_WALLET account is created automatically once the customer's KYC verification is approved; there is no call to create one.

Scope accounts:read

Path parameters

customerIdstring (uuid)Id of the customer.

Response

200 The customer's accounts. Returns the Account list in data.

Errors: 401, 403, 404, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/accounts" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "a2c4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
      "type": "FLYRA_WALLET",
      "accountNumber": "7700012345",
      "balances": [
        {
          "type": "AVAILABLE",
          "amount": "48250.00",
          "currency": "USDB"
        },
        {
          "type": "RESTRICTED",
          "amount": "1200.00",
          "currency": "USDB"
        }
      ],
      "currency": "USD",
      "openedOn": "2026-01-16",
      "status": "ACTIVE"
    },
    {
      "id": "d4f6a8b0-3c5e-4a7b-9d1f-2e4a6c8e0b13",
      "type": "FIAT_DEPOSIT",
      "currency": "USD",
      "openedOn": "2026-01-16",
      "status": "ACTIVE"
    }
  ]
}
GET

Read an account

/v1/customers/{customerId}/accounts/{accountId}

One account with its balances, in the same shape the list returns.

Scope accounts:read

Path parameters

customerIdstring (uuid)Id of the customer.
accountIdstring (uuid)Id of the account.

Response

200 The account. Returns the Account.

Errors: 401, 403, 404, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/accounts/a2c4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "id": "a2c4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
  "type": "FLYRA_WALLET",
  "accountNumber": "7700012345",
  "balances": [
    {
      "type": "AVAILABLE",
      "amount": "48250.00",
      "currency": "USDB"
    },
    {
      "type": "RESTRICTED",
      "amount": "1200.00",
      "currency": "USDB"
    }
  ],
  "currency": "USD",
  "openedOn": "2026-01-16",
  "status": "ACTIVE"
}
GET

Read an account's balances

/v1/customers/{customerId}/accounts/{accountId}/balances

The account's balances in data. AVAILABLE can be spent; RESTRICTED is held. CURRENT and RECEIVABLE are reported under their own names.

Scope accounts:read

Path parameters

customerIdstring (uuid)Id of the customer.
accountIdstring (uuid)Id of the account.

Response

200 The account's balances. Fields below.

Errors: 401, 403, 404, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/accounts/a2c4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f/balances" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "AVAILABLE",
      "amount": "48250.00",
      "currency": "USDB"
    },
    {
      "type": "RESTRICTED",
      "amount": "1200.00",
      "currency": "USDB"
    }
  ]
}

Response body

AttributeTypePresentDescription
dataarray of objectsAlways
data[].amountstringAlwaysDecimal string, for example "48250.00".
data[].currencystringAlwaysA balance's currency can differ from its account's. A ledger-backed wallet balance on a USD account is reported as USDB, the stablecoin ticker it settles in; a balance read from the account's stored columns carries the account's own currency unchanged. Expect USD and USDB both to appear.
data[].typeenumAlwaysAVAILABLE can be spent; RESTRICTED is held. CURRENT and RECEIVABLE are reported under their own names.
AVAILABLERESTRICTEDCURRENTRECEIVABLE

Payment instruments

The instruments a transfer names as its source or destination: the customer's Flyra wallet, virtual accounts and linked accounts. See the Payment instrument model.

POST

Create a payment instrument

/v1/customers/{customerId}/payment-instruments

Opens a virtual account for the customer (OWNED_VIRTUAL_BANK_ACCOUNT), or links a bank or mobile money account they hold elsewhere (LINKED_BANK_ACCOUNT, LINKED_MOBILE_MONEY_ACCOUNT). Cards and US bank accounts cannot be linked.

Scope accounts:write

Headers

X-Idempotency-KeystringRequired A unique key for this request, at most 100 characters, such as a UUID v4. A retry with the same key returns the first response instead of repeating the request. How idempotency works.

Path parameters

customerIdstring (uuid)Id of the customer.

Response

201 The virtual account was provisioned, or already existed. Returns the Payment instrument.

Errors: 400, 401, 403, 404, 409, 422, 500. See Errors.

Request
curl -X POST "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/payment-instruments" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: e82ea632-1c30-47e9-9d3a-744a0add6abc" \
  -H "Content-Type: application/json" \
  -d '{
  "currency": "USD",
  "instrumentType": "OWNED_VIRTUAL_BANK_ACCOUNT",
  "nickName": "USD receipts"
}'
Response
HTTP/1.1 201 Created

{
  "id": "5b1d7e0a-6c2f-4a8e-9b3d-2e4f6a8c0b1d",
  "accountId": "d4f6a8b0-3c5e-4a7b-9d1f-2e4a6c8e0b13",
  "accountNumber": "900123456789",
  "country": "US",
  "currency": "USD",
  "depositInstructions": {
    "accountHolderName": "Andes Trade Partners LLC",
    "accountNumber": "900123456789",
    "accountType": "Checking",
    "bankAddress": "1 Example Plaza, Kansas City, MO 64108",
    "bankName": "Example Bank, N.A.",
    "beneficiaryAddress": "100 Market Street, Suite 300, San Francisco, CA 94105",
    "beneficiaryName": "Andes Trade Partners LLC",
    "paymentRails": ["ach_push", "wire"],
    "routingNumber": "101019644"
  },
  "instrumentType": "OWNED_VIRTUAL_BANK_ACCOUNT",
  "isDefault": true,
  "last4Digits": "6789",
  "nickName": "USD receipts",
  "routingNumber": "101019644",
  "status": "ACTIVE"
}

Request body

AttributeTypeRequiredDescription
accountNamestringNoThe name the account is held in; for a BUSINESS, the company name. In NG it is checked against the bank's record and a mismatch is refused.
accountNumberstringConditionalThe local account number. Required for LINKED_BANK_ACCOUNT except where the corridor identifies the account another way: GB by sort code, the EU by IBAN, BR by PIX key, CO by Bre-B key. For LINKED_MOBILE_MONEY_ACCOUNT, the registered phone number in E.164.
accountOwnerTypeenumNoWho holds the account. Omitted means INDIVIDUAL.
INDIVIDUALBUSINESS
bankCodestringConditionalbankCode from GET /v1/bank-networks for the account's country. Required for LINKED_MOBILE_MONEY_ACCOUNT, and for LINKED_BANK_ACCOUNT in NG, KE, UG and ZA (refused with 422 without it). GB, MX, BR, CO and the euro area take no network.
bankNamestringNo
bicstringConditionalEU. Required alongside the IBAN.
breBKeystringNoCO. The Bre-B key; the provider resolves the bank from it.
clabestringNoMX. The 18-digit CLABE.
countrystringConditionalCountry the account is held in, not the customer's. Required for LINKED_BANK_ACCOUNT and LINKED_MOBILE_MONEY_ACCOUNT; rejected for a virtual account. LINKED_BANK_ACCOUNT: NG, KE, UG, ZA, GB, MX, BR, CO and the euro area. LINKED_MOBILE_MONEY_ACCOUNT: KE and UG only. Any other country is refused with 422 COUNTRY_NOT_SUPPORTED.
currencystringYesISO 4217 code. For OWNED_VIRTUAL_BANK_ACCOUNT, one of USD, EUR, GBP or MXN; any other is refused. For a linked instrument, the currency the account is held in.
ibanstringConditionalEU account number. Required for the European corridors.
instrumentTypeenumYesThe kind of instrument to create. OWNED_VIRTUAL_BANK_ACCOUNT opens a virtual account to receive money; the two LINKED_ types link an account the customer holds elsewhere. OWNED_BANK_ACCOUNT is refused.
OWNED_VIRTUAL_BANK_ACCOUNTLINKED_BANK_ACCOUNTLINKED_MOBILE_MONEY_ACCOUNT
networkNamestringConditionalThe network's display name: name from the same GET /v1/bank-networks row. Required for LINKED_MOBILE_MONEY_ACCOUNT.
nickNamestringNoWhat the customer calls this account. Stored and returned; not sent to the bank.
pixKeystringNoBR. The PIX key value.
pixKeyTypestringNoBR. Which kind of PIX key pixKey is.
sortCodestringConditionalGB sort code, six digits. Required for GB.
GET

List payment instruments

/v1/customers/{customerId}/payment-instruments

The instruments a transfer can name as its source or destination, in data. Every approved customer has an OWNED_WALLET_ACCOUNT: their Flyra wallet.

Scope payment_instruments:read

Path parameters

customerIdstring (uuid)Id of the customer.

Response

200 The customer's payment instruments. Returns the Payment instrument list in data.

Errors: 401, 403, 404, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/payment-instruments" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "5b1d7e0a-6c2f-4a8e-9b3d-2e4f6a8c0b1d",
      "country": "US",
      "currency": "USD",
      "instrumentType": "OWNED_VIRTUAL_BANK_ACCOUNT",
      "isDefault": true,
      "last4Digits": "6789",
      "nickName": "USD receipts",
      "status": "ACTIVE"
    },
    {
      "id": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e",
      "currency": "USD",
      "instrumentType": "OWNED_WALLET_ACCOUNT",
      "isDefault": false,
      "nickName": "Flyra wallet",
      "status": "ACTIVE"
    },
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "bankCode": "6df48502-1ebe-473f-be17-e2cae4dd67ee",
      "bankName": "Example Bank Nigeria",
      "country": "NG",
      "currency": "NGN",
      "instrumentType": "LINKED_BANK_ACCOUNT",
      "isDefault": false,
      "last4Digits": "5678",
      "nickName": "Lagos operating account",
      "status": "ACTIVE"
    }
  ]
}
GET

Read a payment instrument

/v1/customers/{customerId}/payment-instruments/{paymentInstrumentId}

One instrument, in the same shape the list returns. An instrument of a different customer than the one in the path answers 404.

Scope payment_instruments:read

Path parameters

customerIdstring (uuid)Id of the customer.
paymentInstrumentIdstring (uuid)Id of the payment instrument.

Response

200 The payment instrument. Returns the Payment instrument.

Errors: 401, 403, 404, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/customers/3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10/payment-instruments/5b1d7e0a-6c2f-4a8e-9b3d-2e4f6a8c0b1d" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "id": "5b1d7e0a-6c2f-4a8e-9b3d-2e4f6a8c0b1d",
  "accountNumber": "900123456789",
  "country": "US",
  "currency": "USD",
  "depositInstructions": {
    "accountHolderName": "Andes Trade Partners LLC",
    "accountNumber": "900123456789",
    "accountType": "Checking",
    "bankAddress": "1 Example Plaza, Kansas City, MO 64108",
    "bankName": "Example Bank, N.A.",
    "beneficiaryAddress": "100 Market Street, Suite 300, San Francisco, CA 94105",
    "beneficiaryName": "Andes Trade Partners LLC",
    "paymentRails": ["ach_push", "wire"],
    "routingNumber": "101019644"
  },
  "instrumentType": "OWNED_VIRTUAL_BANK_ACCOUNT",
  "isDefault": true,
  "last4Digits": "6789",
  "nickName": "USD receipts",
  "routingNumber": "101019644",
  "status": "ACTIVE"
}
GET

List bank networks

/v1/bank-networks

Every bank and mobile money network Flyra can reach in one country, with the bankCode that Create a payment instrument needs. Read it before linking an account in NG, KE, UG or ZA: send the row's bankCode, and for mobile money its name as networkName. The list is what is active now, so re-resolve a stored code rather than caching it indefinitely. Corridors that identify an account by IBAN, sort code, CLABE or key return an empty list.

Scope payment_instruments:read

Query parameters

countrystringRequired ISO 3166-1 alpha-2 code of the country the account is held in.

Response

200 The country's active networks, possibly empty. Fields below.

Errors: 401, 403, 422, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/bank-networks?country=NG" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "data": [
    {
      "bankCode": "6df48502-1ebe-473f-be17-e2cae4dd67ee",
      "name": "Example Bank Nigeria"
    },
    {
      "bankCode": "3d4d08c1-4811-4fee-9349-a302328e55c1",
      "name": "Lagos Example Bank"
    },
    {
      "bankCode": "9b2f6c1e-5a47-4d3b-8e21-7c4f0a9d6b53",
      "name": "Example Mobile Money"
    }
  ]
}

Response body

AttributeTypePresentDescription
dataarray of objectsAlways
data[].bankCodestringAlwaysSend this as bankCode when linking an account on this network.
data[].namestringAlwaysThe network's display name. For mobile money, send it back as networkName.

Transfers

Quote a rate, move funds, and follow each transfer to a final status, by polling or with the transactions.updated webhook. See the Transfer model.

GET

Quote a rate

/v1/rates

The indicative rate for a corridor and flow, to show a customer before they commit. Nothing is reserved and no expiry is returned. A transfer takes no rate: Flyra prices it when it runs. The rate does not vary by customer today, though customerId is required.

Scope transfers:read

Query parameters

customerIdstring (uuid)Required The customer the quote is for. It does not change the rate today.
sourceCountrystringRequired ISO 3166-1 alpha-2 of the country money leaves.
destinationCountrystringRequired ISO 3166-1 alpha-2 of the country money arrives in.
flowenumRequired The flow the rate is for. Rates differ by flow on the same country pair.
ADD_MONEYSEND_TO_WALLETSEND_TO_BANKWITHDRAW_MONEY

Response

200 The rate. Fields below.

Errors: 401, 403, 404, 422, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/rates?customerId=3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10&sourceCountry=NG&destinationCountry=US&flow=ADD_MONEY" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "rate": 1550.25,
  "sourcedAt": "2026-01-15T09:30:00Z"
}

Response body

AttributeTypePresentDescription
ratenumberAlways
sourcedAtstring (date-time)Always
POST

Create a transfer

/v1/transfers

Moves funds between payment instruments, accounts outside Flyra, and one-time deposit accounts Flyra creates for the transfer. There is no flow or type to set: the two ends say what the transfer is (see the shapes below). Send amount on the source side. Returned PENDING.

Scope transfers:write

Headers

X-Idempotency-KeystringRequired A unique key for this request, at most 100 characters, such as a UUID v4. A retry with the same key returns the first response instead of repeating the request. How idempotency works.

Response

201 The transfer was accepted. Returns the Transfer.

Errors: 400, 401, 403, 404, 409, 422, 500. See Errors.

Request · between instruments
curl -X POST "https://api.flyra.com/v1/transfers" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: 9a4c2e71-5b8d-4f06-a3e9-7c1d0b6f2a58" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "destination": {
    "currency": "USD",
    "paymentInstrumentId": "6f1e2d3c-4b5a-4c69-8d7e-0f1a2b3c4d5e"
  },
  "source": {
    "amount": "250.00",
    "currency": "USD",
    "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e"
  }
}'
Response · between instruments
HTTP/1.1 201 Created

{
  "id": "c7d8e9f0-2a3b-4c5d-8e6f-7a8b9c0d1e2f",
  "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "createdTime": "2026-01-15T09:30:00Z",
  "destination": {
    "id": "88f767ce-7159-4491-9425-18e5180438a6",
    "amount": "250.00",
    "currency": "USD",
    "paymentInstrumentId": "6f1e2d3c-4b5a-4c69-8d7e-0f1a2b3c4d5e"
  },
  "fees": {
    "amount": "0.50",
    "currency": "USD"
  },
  "source": {
    "id": "c268fac3-36ba-48d6-816f-db729135112d",
    "amount": "250.00",
    "currency": "USD",
    "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e"
  },
  "status": "PENDING",
  "updatedTime": "2026-01-15T09:30:00Z"
}
Request · deposit
curl -X POST "https://api.flyra.com/v1/transfers" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: 0f7e3b19-6c2a-4d85-b1f4-8e9a2c5d7b36" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "destination": {
    "currency": "USD",
    "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e"
  },
  "source": {
    "type": "PROVIDED_BANK_ACCOUNT",
    "amount": "50000.00",
    "currency": "NGN"
  }
}'
Response · deposit
HTTP/1.1 201 Created

{
  "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
  "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "createdTime": "2026-01-15T09:30:00Z",
  "destination": {
    "id": "fb5158f1-eaff-4168-8ff5-d4b426b813d5",
    "amount": "32.25",
    "currency": "USD",
    "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e"
  },
  "expiresAt": 1768474800000,
  "expiresIn": {
    "unit": "MINUTES",
    "value": 90
  },
  "fees": {
    "amount": "0.04",
    "currency": "USD"
  },
  "rate": 1550.25,
  "source": {
    "id": "2508e524-14e3-46b9-a23a-443e505f7d4a",
    "type": "PROVIDED_BANK_ACCOUNT",
    "amount": "50000.00",
    "bankAccountDetails": {
      "id": "7ad7065a-0b71-4828-8b7d-4ddeda1c3ba7",
      "accountHolderName": "Andes Trade Partners LLC",
      "accountNumber": "9912345678",
      "bankAccountType": "NGN_DEPOSIT_ACCOUNT",
      "bankName": "Example Bank Nigeria"
    },
    "currency": "NGN"
  },
  "status": "PENDING",
  "updatedTime": "2026-01-15T09:30:00Z"
}

Request body

  • Between two instruments Flyra holds: paymentInstrumentId on both sides.
  • A deposit from an account the customer holds elsewhere: source type CUSTOMER_EXTERNAL_BANK_ACCOUNT or CUSTOMER_EXTERNAL_CRYPTO_ACCOUNT, destination paymentInstrumentId. Flyra collects from the named account.
  • A deposit the customer pays in: source type PROVIDED_BANK_ACCOUNT, destination paymentInstrumentId. Flyra creates a one-time account and returns it in source.bankAccountDetails; the transfer completes when the customer pays into it.
  • A withdrawal: source paymentInstrumentId, destination type CUSTOMER_EXTERNAL_BANK_ACCOUNT or CUSTOMER_EXTERNAL_CRYPTO_ACCOUNT.
AttributeTypeRequiredDescription
customerIdstring (uuid)YesThe customer the transfer is initiated for.
destinationobjectYesOne end of the transfer, with its own currency and amount, so a transfer can change currency. Identify it by paymentInstrumentId or by type, not both. instrumentType and country are not accepted.
destination.amountstringNoDecimal string in this side's currency. Send it on the source only: Flyra prices the transfer from it and fills in the destination amount, which is ignored on a request.
destination.currencystringYesISO 4217 code of the funds on this side. A deposit is quoted in the customer's local currency on the source side (NGN for a Nigerian deposit); every other transfer in USD. Send USD on a side the Flyra wallet is on, even though its balance reads USDB.
destination.paymentInstrumentIdstring (uuid)ConditionalAn instrument Flyra manages; required unless type is sent. Not a virtual account (OWNED_VIRTUAL_BANK_ACCOUNT), which only receives money: use the wallet. Source and destination must be different instruments. Either mistake is refused with 422 VALIDATION_FAILED.
destination.typeenumNoSent instead of paymentInstrumentId for a side Flyra does not hold. CUSTOMER_EXTERNAL_BANK_ACCOUNT and CUSTOMER_EXTERNAL_CRYPTO_ACCOUNT are any bank or crypto account the customer owns. PROVIDED_BANK_ACCOUNT is a one-time account Flyra creates to accept a deposit; its details come back in bankAccountDetails.
CUSTOMER_EXTERNAL_BANK_ACCOUNTCUSTOMER_EXTERNAL_CRYPTO_ACCOUNTPROVIDED_BANK_ACCOUNT
sourceobjectYesOne end of the transfer, with its own currency and amount, so a transfer can change currency. Identify it by paymentInstrumentId or by type, not both. instrumentType and country are not accepted.
source.amountstringNoDecimal string in this side's currency. Send it on the source only: Flyra prices the transfer from it and fills in the destination amount, which is ignored on a request.
source.currencystringYesISO 4217 code of the funds on this side. A deposit is quoted in the customer's local currency on the source side (NGN for a Nigerian deposit); every other transfer in USD. Send USD on a side the Flyra wallet is on, even though its balance reads USDB.
source.paymentInstrumentIdstring (uuid)ConditionalAn instrument Flyra manages; required unless type is sent. Not a virtual account (OWNED_VIRTUAL_BANK_ACCOUNT), which only receives money: use the wallet. Source and destination must be different instruments. Either mistake is refused with 422 VALIDATION_FAILED.
source.typeenumNoSent instead of paymentInstrumentId for a side Flyra does not hold. CUSTOMER_EXTERNAL_BANK_ACCOUNT and CUSTOMER_EXTERNAL_CRYPTO_ACCOUNT are any bank or crypto account the customer owns. PROVIDED_BANK_ACCOUNT is a one-time account Flyra creates to accept a deposit; its details come back in bankAccountDetails.
CUSTOMER_EXTERNAL_BANK_ACCOUNTCUSTOMER_EXTERNAL_CRYPTO_ACCOUNTPROVIDED_BANK_ACCOUNT
GET

List transfers

/v1/transfers

Your organization's transfers, newest first, paginated. Every filter is optional and they combine with AND. status=PENDING matches every transfer that has not reached a final status.

Scope transfers:read

Query parameters

customerIdstring (uuid)Optional Only transfers initiated for this customer.
fromstring (date)Optional Created on or after this date, inclusive, in UTC.
tostring (date)Optional Created on or before this date, inclusive, in UTC.
statusenumOptional Only transfers in this status.
PENDINGPOSTEDSETTLEDREFUNDEDFAILED
pageintegerOptional Page number, starting at 1. Default 1.
sizeintegerOptional Transfers per page. Default 20. Up to 100.

Response

200 The matching transfers. Returns the Transfer list in data.

Errors: 400, 401, 403, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/transfers?customerId=3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10&status=SETTLED&page=1&size=20" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "c7d8e9f0-2a3b-4c5d-8e6f-7a8b9c0d1e2f",
      "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
      "createdTime": "2026-01-15T09:30:00Z",
      "destination": {
        "id": "69fc6d39-d61a-4593-8d6a-ec7b9a322c41",
        "amount": "250.00",
        "currency": "USD",
        "paymentInstrumentId": "6f1e2d3c-4b5a-4c69-8d7e-0f1a2b3c4d5e"
      },
      "fees": {
        "amount": "0.50",
        "currency": "USD"
      },
      "source": {
        "id": "7925add0-4189-43d6-a43a-a1f9e47be6cc",
        "amount": "250.00",
        "currency": "USD",
        "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e"
      },
      "status": "SETTLED",
      "updatedTime": "2026-01-15T09:31:12Z"
    },
    {
      "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
      "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
      "createdTime": "2026-01-15T09:30:00Z",
      "destination": {
        "id": "f7319795-9d06-49c4-b714-24cfd37ed0b2",
        "amount": "32.25",
        "currency": "USD",
        "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e"
      },
      "fees": {
        "amount": "0.04",
        "currency": "USD"
      },
      "rate": 1550.25,
      "source": {
        "id": "b48f3792-c15d-4903-9cf9-6ea4dcf271e1",
        "type": "PROVIDED_BANK_ACCOUNT",
        "amount": "50000.00",
        "currency": "NGN"
      },
      "status": "PENDING",
      "updatedTime": "2026-01-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "totalItems": 2,
    "totalPages": 1
  }
}
GET

Read a transfer

/v1/transfers/{transferId}

The transfer in its current state.

Scope transfers:read

Path parameters

transferIdstring (uuid)Id of the transfer.

Response

200 The transfer. Returns the Transfer.

Errors: 400, 401, 403, 404, 500. See Errors.

Request
curl -X GET "https://api.flyra.com/v1/transfers/c7d8e9f0-2a3b-4c5d-8e6f-7a8b9c0d1e2f" \
  -H "Authorization: Bearer $FLYRA_ACCESS_TOKEN"
Response
HTTP/1.1 200 OK

{
  "id": "c7d8e9f0-2a3b-4c5d-8e6f-7a8b9c0d1e2f",
  "customerId": "3f0c6a52-8a3e-4c47-9a53-6a7d2a8b1f10",
  "createdTime": "2026-01-15T09:30:00Z",
  "destination": {
    "id": "ea106859-f6cf-40de-8263-aaf288beab53",
    "amount": "250.00",
    "currency": "USD",
    "paymentInstrumentId": "6f1e2d3c-4b5a-4c69-8d7e-0f1a2b3c4d5e"
  },
  "fees": {
    "amount": "0.50",
    "currency": "USD"
  },
  "source": {
    "id": "5bfe7a85-fa0d-4af5-bb42-84d4eabb8592",
    "amount": "250.00",
    "currency": "USD",
    "paymentInstrumentId": "8e3a1c5f-0d2b-4f6e-a7c9-4b6d8f0a2c3e"
  },
  "status": "SETTLED",
  "updatedTime": "2026-01-15T09:31:12Z"
}
6 · Notifications

Webhooks

Webhooks tell your system when something changes, such as a transfer settling or a KYC verification being approved, so you do not have to poll. Add an endpoint in the Partner Dashboard under Webhooks; Flyra then sends an HTTPS POST to it for every event.

Delivery

At least once and not strictly in order. Your endpoint must use HTTPS (TLS 1.2 or later) on a public address. Requests come from Flyra's published addresses for your environment, so you can allow-list them.

Acknowledge fast

Answer any 2xx within 10 seconds, then do the work in the background. Answer 410 Gone to switch the endpoint off at once.

Retries

A timeout, a redirect (never followed), a 4xx or a 5xx counts as a failure and is retried up to 10 times over about three days.

The request

HeaderMeaning
X-Flyra-SignatureThe signature to verify; see below.
X-Flyra-TimestampWhen this attempt was sent, in epoch milliseconds. Part of the signed message.
X-Flyra-Event-IdThe event id, equal to the body's id. The same on every retry: deduplicate on it.
X-Flyra-Event-TypeThe event type, equal to the body's type.
X-Flyra-Delivery-IdThis delivery. New when an event is redelivered.
X-Flyra-AttemptThe attempt number, from 1.
X-Flyra-Webhook-IdThe id of your endpoint that receives the request.

The body is the same envelope for every event:

idstring (uuid)The event id.
typestringThe event type, such as transactions.updated.
apiVersionstringThe version of the body's schema, such as 2026-10-23.
environmentstringsandbox, or production for live.
organizationIdstring (uuid)Your organization.
occurredAtstring (date-time)When the change happened.
resourceobjectThe type and id of the resource the event is about.
sequenceintegerGrows with every change to the resource.
dataobjectThe full resource as it is now.
changedobjectold and new values of the fields that changed. On a created event, old is {}.
Webhook request · test event
POST /your/webhook/path HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: Flyra-Webhooks/1.0
X-Flyra-Event-Id: 0192f1c2-45aa-7bb4-8000-1f01236f91b3
X-Flyra-Event-Type: webhook.test
X-Flyra-Timestamp: 1792000000000
X-Flyra-Signature: v1:k_testvect:nzmfN474499k0DTbp4Z09cxlb6HSV2A2ostGhJgITLY
X-Flyra-Delivery-Id: 6a1f0e8c-1b2d-4e3f-8a9b-0c1d2e3f4a5b
X-Flyra-Attempt: 1
X-Flyra-Webhook-Id: 0192f1c2-4528-7ba6-8000-1f01236d8fb1

{"id":"0192f1c2-45aa-7bb4-8000-1f01236f91b3","type":"webhook.test","apiVersion":"2026-10-23","environment":"sandbox","organizationId":"0192e5a4-7c1b-7d3e-9f20-6a8b4c2d1e0f","occurredAt":"2026-10-23T11:00:00.000Z","resource":{"type":"webhook_endpoints","id":"0192f1c2-4528-7ba6-8000-1f01236d8fb1"},"sequence":1,"data":{"endpointId":"0192f1c2-4528-7ba6-8000-1f01236d8fb1","sentBy":"0192f1c2-4569-7bad-8000-1f01236e90b2","sentAt":"2026-10-23T11:00:00.000Z"},"changed":{"old":{},"new":{"endpointId":"0192f1c2-4528-7ba6-8000-1f01236d8fb1","sentBy":"0192f1c2-4569-7bad-8000-1f01236e90b2","sentAt":"2026-10-23T11:00:00.000Z"}}}

Verify the signature

Verify every request before you trust it. Each endpoint has a signing secret, shown once when you create or rotate it, that looks like flyra_whsec_ followed by 43 characters, with a key id such as k_a1b2c3d4.

  1. Read the raw request body as bytes, before parsing the JSON.
  2. Build the message: the X-Flyra-Timestamp value, a full stop ., then the raw body.
  3. Compute HMAC-SHA256 of the message, keyed with the whole secret string exactly as shown, flyra_whsec_ prefix included. Do not decode the secret.
  4. Encode the result as base64url without = padding.
  5. X-Flyra-Signature holds one or more values separated by , (two while you rotate the secret), each v1:<keyId>:<signature>. Accept the request if one value with a key id you hold matches your result, using a constant-time comparison.
  6. Reject the request if the timestamp is more than five minutes away from your clock.
To test your code, verify the test event shown above. With the secret flyra_whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8 (key id k_testvect), timestamp 1792000000000 and the body on one line with no trailing newline, the header must be v1:k_testvect:nzmfN474499k0DTbp4Z09cxlb6HSV2A2ostGhJgITLY. The samples reject events more than five minutes old, so pin the clock to that timestamp (or skip the age check) when testing against this vector.
Node.js
import crypto from 'node:crypto'

// rawBody is a Buffer of the request body exactly as received.
// Returns false (never throws) for missing, malformed or forged headers.
export function verifyFlyraSignature(rawBody, headers, secrets /* { k_a1b2c3d4: 'flyra_whsec_...' } */) {
  const timestamp = headers['x-flyra-timestamp']
  const signatures = headers['x-flyra-signature']
  if (typeof timestamp !== 'string' || typeof signatures !== 'string') return false
  const sentAt = Number(timestamp)
  if (!Number.isFinite(sentAt) || Math.abs(Date.now() - sentAt) > 5 * 60 * 1000) return false
  const message = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody])
  return signatures.split(',').some((value) => {
    const [version, keyId, signature] = value.trim().split(':')
    const secret = secrets[keyId]
    if (version !== 'v1' || !secret || !signature) return false
    const expected = Buffer.from(crypto.createHmac('sha256', secret).update(message).digest('base64url'))
    const received = Buffer.from(signature)
    return expected.length === received.length && crypto.timingSafeEqual(expected, received)
  })
}
Python
import base64, hashlib, hmac, time

def verify_flyra_signature(raw_body: bytes, headers, secrets: dict) -> bool:
    """Returns False (never raises) for missing, malformed or forged headers."""
    timestamp = headers.get("X-Flyra-Timestamp", "")
    try:
        sent_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() * 1000 - sent_at) > 5 * 60 * 1000:
        return False
    message = timestamp.encode() + b"." + raw_body
    for value in headers.get("X-Flyra-Signature", "").split(","):
        version, key_id, signature = (value.strip().split(":") + ["", "", ""])[:3]
        secret = secrets.get(key_id)
        if version != "v1" or not secret:
            continue
        digest = hmac.new(secret.encode(), message, hashlib.sha256).digest()
        expected = base64.urlsafe_b64encode(digest).rstrip(b"=")
        if hmac.compare_digest(expected, signature.encode()):
            return True
    return False

Event types

Every resource sends a created event when it appears and an updated event when it changes. Both carry the full resource in data, so one handler per resource is enough. Removal, closure and cancellation arrive as updated events with the new status; there are no deleted events.

ResourceEvent types
Transactions (transfers)transactions.created, transactions.updated
Disputestransactions.disputes.created, transactions.disputes.updated
Customerscustomers.created, customers.updated
Related partiescustomers.related_parties.created, customers.related_parties.updated
Documentscustomers.documents.created, customers.documents.updated
KYC verificationscustomers.kyc_verifications.created, customers.kyc_verifications.updated
Onboarding applicationscustomers.onboarding_applications.created, customers.onboarding_applications.updated
Accountsaccounts.created, accounts.updated
Payment instrumentspayment_instruments.created, payment_instruments.updated
Cardscards.created, cards.updated
Card transactionscards.transactions.created, cards.transactions.updated
Testwebhook.test, sent when you press Send test event in the Partner Dashboard

transactions.updated

A transfer changed. It starts PENDING and ends SETTLED or FAILED; it can also report POSTED and REFUNDED.

PENDINGSETTLEDorFAILED

customers.kyc_verifications.updated

A KYC verification changed. It starts PENDING and ends APPROVED or DECLINED; on the way it can report IN_PROGRESS, PENDING_USER_ACTION, IN_REVIEW. PENDING_USER_ACTION means you need to collect something further from the customer.

PENDINGAPPROVEDorDECLINED

Handling events

  • Ignore an event whose id you have seen in the last 72 hours.
  • Apply changed.new only when sequence is higher than the last one you applied for that resource. If you notice a gap, read the resource with a GET.
  • Respond with 2xx quickly and do slow work after acknowledging.
  • New fields and new status values can appear without notice. Ignore what you do not recognise.
Flyra Partner API · v1.0.0Questions about your integration? Contact your Flyra partner manager.