⎋ Sign in
Request
En
I am ready for a long road flight for working with a week- or months-long projects.
Отправить заявку
Войти
Cardoo.
Version 1.2
Publication date: 11.05.2021
Integration
En ▾
Overview
Using our API you can request pricing of our products, create orders, get details of created orders, cancel them, request refund etc.

After creating an order you will get in response a link to our Order's Customer Flow which should be given to a customer (e.g. you can redirect a customer or send it via email/sms).

To use our API you need to have a secret token which will be provided by our team. Authentication is done by using a secret token in a HTTP header in all API requests as follows: Access-Token: *secret-token*

IMPORTANT: We represent monetary values as integers, in cents.

For example, 11.54 euros would be 1154 eurocents. Also, we require to provide a currency in ISO format.
E.g.:
{
	"amount": {
		"cents": 1154,
		"currency_iso": "eur"
	}
}
Integration usually include these steps:

  1. Price request
  2. Order creation request
  3. Callback endpoints

So, you make two requests to our server and expect to receive callbacks informing you on customer's journey through the Customer Flow.

You can send a single price request for a batch of offers for your search results page or you can send one during the booking process of a single offer.

For POST requests HTTP Header "Content-Type" should be set to "application/json".

To enable test mode add to Order body this key-value:
{
	...
	“test”: true
}
Test mode allows you to use test credit card data and bypass some manual processes during Customer Flow.

Customer Flow overview
After you created an Order and a customer was redirected or opened an order's flow link, these steps will occur:

  1. Entering credit card information and paying the required amount
  2. Uploading identifying documents (such as ID card, passport, driver's license)
  3. Signing the order using one-time password sent via SMS

Upon finishing each step either with success or with failure we can communicate the result via callback functionality.

For step 3 we don't send a failure callback for a NOT signing the order. Order should be consider not signed by your system until notified otherwise, i.e. via a success callback.

Customer will be redirected to specified URLs (specified in the Order creation request) upon these events:
1. Payment failure
2. Customer Flow failure
3. Customer Flow success
General Order creation process
  1. To get a correct pricing of our products for your specific proposals send a POST request to /partner_api/pricing_request

  2. To issue an order in our system and get a link to direct a customer to our flow send a POST request to /partner_api/orders

You can reference API schemas in our swagger https://api.cardoo.finance/swagger

You can check the integration by send a GET request to /partner_api/orders/:id (or without id if you want to get a list of your orders) and compare all the values.
Customer Redirects
When we are integrated as an acquiring service we suggest for you to provide to redirect URLs in case of:
  • a payment failure;
  • a customer flow failure;
  • when a customer successfully completes the flow, they will be redirected back to your website (you provide a particular URL during Order creation process).

E.g., part of JSON would be like:
{
	"redirects": {
		"payment_step": {
			"failure_url": "https://your-failed-payment-page"
		},
		"flow_completion_step": {
			"success_url": "https://your-successful-order-page",
			"failure_url": "https://your-failed-cardoo-order-page"
		}
}
Callbacks to your system
We provide callback functionality for important events, such as payment status changes or when a customer finishes all the legal steps required for our services. We don't send a failure callback for a NOT signing the order. Order should be consider not signed by your system until notified otherwise, i.e. via a success callback.

We use POST-request with an empty body to the provided URLs in an Order creation request. That means that for every event you should use a unique URL.

If you want to receive a callback upon successful payment, provide a specific for this particular event a URL which will receive a POST-request.

For example, part of a JSON in the Order Creation request will look like:
{ ...
	"callbacks": {
		"payment_step": {
			"success_url": "https://payment_success_callback_url",
			"failure_url": "https://payment_failure_callback_url"
		},
		"identification_step": {
			"success_url": "https://id_documents_success_callback_url",
			"failure_url": "https://id_documents_failure_callback_url"
		},
		"signing_step": {
			"success_url": "https://customer_flow_success_callback_url"
		}
	}
}
Refund
To initiate a refund process send a POST request to /partner_api/refund_requests with order_id and an amount. E.g.:
{
	"order_id": "some-id",
	"amount": {
		"value": 1300,
		"currency": "eur"
	 }
}
Cancelling the Order
To cancel the Order send a POST request to /partner_api/orders/:id/cancel with an optional reason for cancellation.
E.g. { "reason": "schrodingers reason" }
API Reference
Give us your address and we'll send you an offer just for you
Get Cardoo today
Sign up
Product
About
Help
Get offer