📘

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, via the GET /orders/{uuid}/payment-details endpoint.
3. Token release — Once the end user completes the SEPA payment using the provided reference, the tokens are automatically released to the specified wallet address.

The current state of the transaction can be retrieved at any time using the order status endpoint.

Authentication

No authentication is required at this time.

---

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 kycClientUuid 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 kycClientUuid 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 vendor identifier, the kycClientUuid, the recipient wallet address, the currency, and the amount. The response returns the complete order object along with the order UUID, which is used to retrieve payment details and status.

• 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 in the next step.

---

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 full order object, including fields such as orderStatus, sepaReference, and transaction hashes.

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