CryptoPocket Integration Guide — Buy Flow (On-Ramp)

This guide describes how to integrate CryptoPocket’s API to let your customers buy cryptocurrency and use it in your remittance process.

Prerequisites

Before calling the API, CryptoPocket will provide you with:

API Key and API Secret

Base URL (production or sandbox)

Optional: IP whitelist configuration

Step 0 — Authenticate

All API requests require an auth token in the header:

auth: <your_token>

Obtain the token by calling:

POST /api/authenticate

Body:

{
  "api_key": "your_api_key",
  "api_secret": "your_api_secret"
}

Response: a token valid for ~24 hours. Refresh it before expiry.

Step 1 — Build an estimation form (optional)

Use the Quote endpoint to show your customer how much crypto they will receive for a given EUR amount.

GET /api/quote

Query params:

Param	Required	Description
`amount`	Yes	EUR amount to buy
`symbol`	Yes	Crypto symbol (e.g. `USDC`, `BTC`)
`chain`	No	Blockchain (default: `polygon`)
`payment_type`	Yes	e.g. `card`, `PSD2`, `TRANSFER`

Response: estimated crypto amount (tokens).

You can also call GET /api/available-assets to list supported coins and blockchains.

Step 2 — Register the customer (KYC)

When your customer is ready to operate, register them with:

POST /api/registerUser

Minimum body:

{
  "name": "John",
  "email": "john@example.com"
}

Response (key fields):

Field	Description
`id`	Customer ID — save this in your database
`kyc_form_url`	URL to redirect the customer to complete KYC

Your action: redirect the customer to kyc_form_url.

Optional: send callback_url if you want the customer redirected back to your app after KYC.

Step 3 — Poll KYC status

While the customer completes KYC, poll:

GET /api/kyc/check?user_id={id}

Stop polling when kyc_status is:

Status	Meaning
`valid`	KYC approved — proceed to payment
`fail`	KYC rejected — do not proceed

Intermediate statuses (unused, processing) mean KYC is still in progress.

Alternative: subscribe to KYC webhooks instead of polling (contact us for setup).

Step 4 — Create a guided payment intent

Once KYC is valid, create the payment:

POST /api/createGuidedPayment

Body:

{
  "user_id": 12345,
  "coin_symbol": "USDC",
  "coin_chain": "polygon",
  "fiat_amount": 100,
  "payment_type": "card",
  "external_id": "your-remesa-reference-001"
}

Field	Required	Description
`user_id`	Yes	Customer ID from Step 2
`coin_symbol`	Yes	Crypto to buy
`coin_chain`	Yes	Blockchain
`fiat_amount`	Yes	Amount in EUR
`payment_type`	No	Default: `card`
`external_id`	No	Your internal reference (recommended for remittances)

Note: Guided payment is currently available for EUR only.

Response (key fields):

Field	Description
`payment_id`	Payment token — save this in your database
`gateway_url`	URL to redirect the customer to pay

Your action: redirect the customer to gateway_url.

Step 5 — Poll payment status

Poll until the operation completes:

GET /api/payment/{payment_id}

Relevant statuses:

Status	Meaning
`started`	Payment created, awaiting customer action
`payment_received`	Customer paid — crypto dispatch in progress
`coins_sent`	Crypto sent to wallet — operation complete

When status is coins_sent, the response may also include txid (blockchain transaction hash).

Alternative: subscribe to webhooks (PAY_IN, COINS_SENT) to receive notifications instead of polling.

Step 6 — Continue your remittance process

When the payment reaches coins_sent, the cryptocurrency is available in the configured wallet.

Flow diagram

What you should store

Your DB field	Source
`cryptopocket_user_id`	`id` from `registerUser`
`cryptopocket_payment_id`	`payment_id` from `createGuidedPayment`
`external_id`	Your own remittance reference

CryptoPocket Integration Guide — Buy Flow (On-Ramp)