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 may require a rate before creation. Use GET /v1/rates to retrieve rates and pass the returned rate_id when the funding account requires one. 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

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.

​

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.
3. Wait for verification status to become approved.
4. Create the virtual account.

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.

​

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

Partners can still charge users in their own product flow, but they must model, collect, and reconcile that fee themselves until Daya exposes native custom-fee support.

​

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.
• 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

​

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.