Full API Integration
Full API Integration
A full API integration gives you complete control over the end-user experience. Rather than embedding a Coinify-hosted UI, you build your own — and call the Coinify Trade API directly to power it.
This is the most flexible integration path, but also the most involved. Choose it when you need full ownership of the UI, are building a native mobile app, or have UX requirements that the Trade Widget can't accommodate.
Not sure this is right for you? See Integration Options → for a side-by-side comparison of all three integration paths.
How the API works
The Trade API is a standard REST API — resource-oriented URLs, JSON request and response bodies, and HTTP status codes. All endpoints that act on behalf of an end-user require authentication via a Bearer token.
For a full breakdown of request/response format and status codes, see General API Overview →.
The end-user flow
Every end-user goes through the same high-level journey before they can trade. Here's how that maps to API calls:
1. Sign up — create a Coinify trader account for the end-user. The Frictionless Sign-up Flow → is recommended for the best UX, as it handles this invisibly in the background without requiring the user to interact with a Coinify sign-up screen.
2. Authenticate — sign the end-user in to get an access_token and refresh_token. Again, the Frictionless Sign-in → flow is recommended, using an offline_token to authenticate silently on their behalf.
3. Collect mandatory information — before an end-user can trade, a set of regulatory data points must be collected and submitted via API. The required fields differ for individual vs corporate users. See Mandatory User Information →.
4. Complete KYC — individual users only. Initiate an identification attempt, redirect the user to the KYC URL, and handle their return. Corporate users go through a KYB email flow instead. See KYC / Identity Verification →.
5. Get a trade quote — fetch a price quote for the desired currency pair. The returned quoteId is required to create the actual trade. See Trade Quotes →.
6. Create a trade — use the quoteId to create a Buy or Sell trade. See Buy Crypto — Card Payment →, Buy Crypto — Bank Transfer →, or Sell Crypto → depending on the trade type.
7. Handle payment — direct the end-user to complete payment based on the trade type:
- Card: redirect to Coinify's Payment Page using the
redirectUrlfrom the trade response - Bank transfer: display the
transferIn.detailsbank account info for the user to pay into - Sell (blockchain): display the
transferIn.detailswallet address for the user to send crypto to
8. Track trade status — listen for webhook events to know when a trade's state changes. See Webhooks →.
Views to implement
Your UI needs to support the following screens for a complete integration:
| View | Purpose |
|---|---|
| Trade quote | Show the exchange rate and fees so the end-user can decide whether to proceed |
| Order summary | Show a confirmation of trade details before the end-user commits and is prompted to pay |
| Credit card payment | Redirect the end-user to Coinify's Payment Page to complete a card Buy trade |
| Bank account registration | Collect and store the end-user's bank account details, required for Sell trades |
| KYC redirect | Redirect the end-user to Coinify's identity verification flow and handle their return |
| Trade history | Let the end-user view their past trades and current trade states |
The Trade Widget is a useful reference for how these flows and views can be structured. See Trade Widget →.
Next steps
From here, the natural reading order follows the end-user journey:
- Sign-up Flows → — manual and frictionless sign-up options
- Sign-in Flows → — password, refresh token, and offline token options
- Mandatory User Information → — what to collect and when
- KYC / Identity Verification → — handling identity verification
- Trade Quotes → — fetching a quote before creating a trade