Partner Integration

​

What Is the Daya API?

The Daya API lets businesses move money between Nigerian Naira (NGN), USD bank rails, and stablecoins such as USDC and USDT through one programmable interface. Instead of building exchange logic, wallet infrastructure, KYC flows, banking rails, and payout operations from scratch, partners can integrate Daya and focus on their product experience. Common products partners can build include:

• A fintech app that lets Nigerian users buy stablecoins without leaving the product.
• A savings, payroll, or marketplace app that lets users cash out stablecoins into Nigerian bank accounts.
• A business banking or creator product that gives customers USD virtual accounts and outbound USD transfer options.

​

Sandbox vs Production

All new partners should start in sandbox. Sandbox testing protects the partner, Daya, and end users from real-money mistakes while implementation details are still being validated.

​

Production Access and KYB

Production access requires KYB verification. Treat KYB as part of the launch path, not as optional admin work. KYB unlocks production API keys, real money movement, USD virtual accounts, and USD transfer rails where available.

1. Request production access through support@daya.co or the dedicated partner channel.
2. Submit the KYB form and business documents, including company registration, director details, and proof of business.
3. Wait for Daya review and approval.
4. Accept the production dashboard invite using the exact invited email address.
5. Generate production API keys and configure webhooks.

If the dashboard invite link does not work, ask Daya to resend the invite or verify the email address.

​

Dashboard Setup

The dashboard is where partners manage API keys, webhooks, team access, balances, and transaction monitoring.

• Generate and rotate API keys separately for sandbox and production.
• Configure webhook endpoints before launch.
• Add team members with appropriate access.
• Monitor merchant balances, deposits, transfers, and payout status.

​

Webhook Setup

1. Add the webhook endpoint URL in the Daya dashboard.
2. Configure your server to accept Daya webhook requests, including IP allowlisting where required.
3. Verify webhook signatures using the webhook verification docs.
4. Log event IDs and resource IDs so support can investigate issues quickly.

For staging and production, use a publicly accessible HTTPS endpoint that remains stable over time. Temporary tunneling services such as ngrok, Cloudflare Tunnel, or localtunnel should only be used during active local development and testing.

​

Balance Model

Balance handling is one of the most important concepts to understand before building on Daya. Many issues come from assuming Daya maintains individual user balances or that all funds are immediately withdrawable. Transfers and payouts are funded from withdrawal balance, not collection balance. Ensure sufficient withdrawal balance is available before initiating outbound money movement. A typical ledger flow:

1. A user deposits funds or receives money through a Daya-powered flow.
2. The funds settle into the merchant’s Daya balance.
3. Daya sends webhook events and exposes transaction state through the API.
4. The partner credits or debits the user on the partner’s own ledger.
5. The partner initiates payout, transfer, or withdrawal from merchant balance when needed.

​

Rates and Rate IDs

Temporary funding account flows that use a quoted conversion require a rate before creation. Use GET /v1/rates to retrieve rates and pass the returned rate_id when creating a temporary funding account that performs a quoted conversion. This includes temporary NGN funding accounts settling to INTERNAL_BALANCE or ONCHAIN, and temporary crypto funding accounts settling through NGN_PAYOUT. Respect the rate expiry window. If a rate expires before creation or before payment arrives, the deposit may be flagged for review instead of settling automatically. When comparing rates, compare the same asset, amount, direction, timestamp, and whether you are looking at a gross FX rate or final net destination amount after fees.

​

Onramps: NGN to USDC/USDT

An onramp lets a customer pay NGN into a Daya bank account. Daya records the incoming money as a deposit, then settles the value to your Daya balance or to an onchain stablecoin address. New integrations create onramps with POST /v1/funding-accounts using:

​

Onramp Fees

When presenting onchain settlement amounts to your users, show the crypto settlement fee before they confirm the payment. For example, if the estimated stablecoin amount is 1.07 USDC and the crypto settlement fee is 0.10 USDC, the user should see that the final amount delivered onchain is 0.97 USDC. Pass the customer’s name when creating an onramp. The name can appear on the virtual account holder details, and Nigerian users often verify the account name before sending a bank transfer.

​

Offramps: USDC/USDT to NGN

An offramp gives your customer a crypto address for sending USDC or USDT into Daya. Daya records the incoming crypto as a deposit, then settles the value to your Daya balance or to a Nigerian bank account. New integrations create offramps with POST /v1/funding-accounts using:

​

Offramp Fees

​

Bank Account Resolution

Before creating an offramp with NGN_PAYOUT, resolve the destination account using POST /v1/banks/resolve. This verifies the bank account number and account holder name before funds are committed.

​

Minimum Deposit Handling

Deposits below the minimum supported threshold can be flagged and may not be eligible for settlement. Do not present a flagged deposit as a failed deposit. Clearly communicate that the deposited amount did not meet the minimum settlement requirement and provide support guidance.

​

Payout Timing

NGN bank payouts are not guaranteed to be instant. Daya depends on third-party payout providers. Provider incidents can delay completion. After an offramp deposit is received, NGN payout delivery happens in the background as part of deposit settlement. Track the customer-facing state from the deposit status, settlement_status, and deposit.* webhooks. Your product can show states such as Deposit received, Settlement processing, Settlement settled, Settlement failed, or Requires review. Do not wait for a separate transfer or payout webhook for funding-account offramps, and do not show a generic complete state as final bank receipt until the deposit settlement has completed.

​

Supported Chains and Tokens

Chain and token support is runtime-configured. Partners should not hard-code support from this guide, screenshots, or old conversations. Always call GET /v1/supported-chains before showing a chain/token option to users or before attempting onchain settlement. If you receive VALIDATION_FAILED - unsupported settlement chain/token, the chain/token is not enabled for the requested direction. Check both the chain and token with /v1/supported-chains before retrying.

​

USD Virtual Accounts

A USD virtual account is a US bank account provisioned for a verified customer so the customer can receive USD payments. The sender does not need to understand crypto. Typical prerequisites:

1. Create a customer.
2. Complete required verification: tier 1 BVN + selfie and tier 2 KYC for individual people, or business KYB for entities.
3. Wait for verification status to become approved.
4. Create the virtual account.

For individual customers, submit POST /v1/customers/{id}/tier1-verification first, then submit POST /v1/customers/{id}/tier2-verification with the individual KYC fields. For a business or entity customer, use the tier 2 endpoint with customer_type: "business" and the business KYB fields. Both flows update the same customer object; after approval, tier_2_kyc_complete becomes true and the customer can be used with POST /v1/virtual-accounts. A USD virtual account does not maintain a separate spendable balance for the customer inside Daya. Deposits settle into the merchant collection balance. The partner must credit the customer on its own ledger using deposit webhooks and reconciliation. Verification failures and provider outages should be handled differently. A verification rejection usually requires corrected information from the customer. A provider outage or upstream service error should be retried after a short backoff before asking the customer to resubmit documents.

​

Developer Fees

Developer fees let you keep a percentage of received deposits while Daya reports the split for reconciliation. Configure a developer fee by sending developer_fee.percentage when creating a funding account, legacy onramp, legacy offramp, or USD virtual account. Use a decimal string from 0 to 50. Omit developer_fee to use 0%. developer_fee.percentage is a percentage value, not basis points. For example: This is different from fee_bps in rate responses, where 50 basis points means 0.5%. The percentage applies to deposits received through that account. Deposit responses and deposit webhooks include developer_fee and customer_amount after Daya calculates the split. Use customer_amount when crediting the customer in your own ledger. For onramps and offramps, the developer fee is deducted before the final customer amount is calculated. It is not added as an extra charge on top of the amount the user sends. Use developer_fee.amount and developer_fee.currency to track the exact fee kept by your merchant account, and use customer_amount to know the final amount left for the customer. Flat developer fees, such as NGN 500 or $1 per transaction, are not currently supported through developer_fee. If you charge users outside Daya, make that fee clear in your own product and reconcile it separately.

​

Transfers

Transfers are merchant-initiated sends of funds to a bank recipient. They are funded from withdrawal balance, not collection balance. Use POST /v1/transfers to create a transfer.

​

NGN Transfers

NGN transfers send Naira to Nigerian bank accounts. Resolve bank account details before creating the transfer and make sure the relevant withdrawal balance is funded.

​

USD Transfers

USD transfers send money through supported USD rails. The customer on whose behalf the partner is sending may need additional verification, especially for inline USD bank or SWIFT destinations.

​

Idempotency

Always include an Idempotency-Key header when creating transfers or other money-movement requests that may be retried. Use a unique UUID per logical transfer attempt to avoid duplicates.

​

Fee Reference

If you also charge users outside Daya, make that clear in your product and reconcile it separately from the Daya developer fee fields.

​

Going Live Checklist

• Complete KYB and receive production approval.
• Log in to the production dashboard with the exact invited email.
• Generate production API keys and store them securely server-side.
• Set up the production webhook endpoint and signature verification.
• Configure webhook IP allowlisting if required.
• Check /v1/supported-chains at runtime and build direction-aware controls.
• Test onramp flows with exact amounts and minimum-amount edge cases.
• Test offramp flows including bank account resolution, delayed processing states, and webhook finalization.
• Test any developer_fee.percentage configuration, including the 0 to 50 accepted range and the deposit customer_amount your ledger will credit.
• Confirm pricing accounts for Daya fees and any partner-side fee.
• Add idempotency keys to retryable money-movement requests.
• Implement reconciliation jobs for webhooks, API state, and partner ledger state.

​

Troubleshooting

​

Tier 2 and KYC errors

Some Tier 2 errors are request validation failures before Daya sends the customer to the verification provider. Other statuses come from provider review. Treat them differently so customers are not asked to resubmit the wrong information.

​

FAQ

​

Why did the user get refunded?

Temporary onramps require the exact amount returned by the API response. Amount mismatch can trigger an automatic refund or review state.

​

Why is the API offramp rate different from the Pro app market or order book rate?

The Pro app order book reflects user bids and offers at that moment, while the Business API rate is what Daya can offer and execute within the rate expiry window. They are separate pricing surfaces and may differ. For offramps, confirm the partner is using the SELL rate and comparing the same asset, amount, direction, and timestamp.

​

Is Aptos supported?

Aptos support is available only when the live supported-chains endpoint says the exact token and direction are enabled. Check USDT and USDC separately and check deposit_enabled versus withdraw_enabled.

​

Can partners configure a custom flat fee in Daya?

Not currently. Partners should implement any additional fee in their own product flow until Daya exposes native custom-fee support.

​

Are virtual accounts and ACH the same thing?

No. Virtual accounts receive funds. ACH, Wire, RTP/FedNow, and SWIFT are transfer rails for sending funds.

​

Support and Escalation

When escalating, include environment, endpoint, request body with secrets removed, request_id, funding account ID, deposit ID, transfer ID, chain/token, bank name where relevant, timestamp, and webhook event IDs or delivery logs.