📘

Getting Started with Crossbill API

The Crossbill API provides an interface for initiating and tracking fiat-to-crypto transactions.

Each transaction is represented by an Order, which records the state of the operation throughout its lifecycle. Orders are created and accessed through the API, allowing clients to initiate a transaction and retrieve its current status.

The system coordinates the processing of the transaction, including the interaction between fiat payment confirmation and on-chain execution. The API exposes endpoints required to create orders and track order status.

The API also includes KYC endpoint used to submit user identification data. Submitted KYC information is processed and stored by the platform.

Base URLs

Service	Base URL
Orders	https://api.crossbill.com
KYC	https://kyc.crossbill.com

All order endpoints (/orders/*) are served from https://api.crossbill.com. The KYC endpoint (/kyc/add) is served from https://kyc.crossbill.com.

Transaction Lifecycle

A fiat-to-crypto transaction progresses through several stages coordinated by the platform.

1. Order creation — The merchant creates an on-ramp order on behalf of the end user via the POST /orders/create endpoint.
2. Payment instructions — The merchant retrieves the fiat payment details for the end-user, including the (SEPA) reference, in the response body after order creation.
3. Inquire any time — The merchant can track and receive order and payment details and current order status via the GET /orders/{uuid}/payment-details endpoint.
4. Order completion — Once the end-user completes the (SEPA) payment using the provided reference and once the SEPA payment has been completed, the tokens are automatically released to the specified wallet address and the order is completed.

Authentication

All endpoints require a Bearer token. To obtain a token, use the POST /auth/token endpoint, passing your merchant credentials as HTTP Basic auth. Tokens expire after 15 minutes, so your integration should handle 401 responses by fetching a fresh token and retrying. For more information visit: Get auth token →

---

How It Works

---

Step 1 — Submit KYC Data

Before an order can be created, the end user must be registered through the KYC endpoint. The response returns a complete KYC object along with the end user's UUID, which should be stored and used later as kycUserUuid when creating an order.

• Endpoint: POST /kyc/add
• Purpose: Submit the end user's identification data required for compliance.
• API Reference: POST /kyc/add

Save the returned uuid from the response — this is your kycUserUuid and you'll need it to create orders.

---

Step 2 — Create an Order

Once the user has been registered, create an order for the transaction. The order request includes the amount, the currency (currently only EUR is supported), the recepientAddress (Arbitrum USDC wallet address) and the kycUserUuid. The response returns the complete order object along with the payment details [iban, bic, (SEPA) reference] and orderStatus.

• Endpoint: POST /orders/create
• Purpose: Create a fiat-to-crypto transaction order for a KYC-registered user.
• API Reference: POST /orders/create

Save the returned uuid — you'll use it to retrieve payment details if needed.

---

Step 3 — Retrieve Payment Details and Status

After the order is created, call the payment details endpoint using the returned order uuid. This endpoint returns the complete order object along with the payment details [iban, bic, (SEPA) reference] and status and orderStatus.

• Endpoint: GET /orders/:uuid/payment-details
• Purpose: Retrieve the payment instructions and the current state of the order.
• API Reference: GET /orders/:uuid/payment-details

Replace :uuid with the uuid returned from the Create Order response.

---

Order Statuses

Each order progresses through a set of statuses that represent the current stage of the transaction. The order status can be retrieved at any time using the payment details endpoint.

Status	Description
CREATED	The order has been successfully registered and the system has prepared the data required for the next steps of the transaction.
COMPLETED	The required payment has been confirmed and the on-chain execution associated with the order has been completed.
FAILED	The order could not be completed due to a processing error or invalid transaction data.

The current order status can be retrieved using the GET /orders/:uuid/payment-details endpoint in the Orders section of the API Reference.

---

Get All Orders

Merchants can retrieve a list of all their orders using the GET /orders endpoint. The endpoint supports pagination via two query parameters:

Parameter	Default	Description
limit	50	Maximum number of orders returned. Cannot exceed 50.
offset	0	Number of orders to skip. Used for pagination.

Example:

HTTP

GET /orders?limit=10&offset=0
Authorization: Bearer your-token-here

---

Webhooks

After an order is completed, CrossBill sends an HTTP POST request to the callback URL you provide. This allows your integration to react to completed orders in real time without polling.

Subscribing

To subscribe, provide CrossBill with your callback URL. We will generate a shared secret for you, which you use to verify the authenticity of incoming webhook requests.

Verifying Webhooks

Incoming webhooks include an X-Webhook-Signature header. The signature is an HMAC-SHA256 hash of the request body using your shared secret. Always verify this signature before processing the webhook.

Webhook Headers

HTTP

Content-Type: application/json
X-Webhook-Signature: <hmac-sha256-signature>

Webhook Body

JSON

{
  "event": "order.completed",
  "status": "COMPLETED",
  "orderUuid": "5000833f-9a9e-4b4f-811e-a91cda8dc053",
  "userUuid": "658a2c2e-c90a-4dc1-b7ed-d3f43e0ac398",
  "reference": "your-sepa-reference",
  "recipientAddress": "0x76fee27e8A2a9EE1d9b310AC33fc37983cDA96Af",
  "transactionHash": "0x92b87d8c970558d002c88c7146055f555df0352c4c35a8ef8b8f334ed1595757",
  "timestamp": "2024-11-14T20:20:20.000Z"
}