Cauri Payment System REST API documentation
version v1
https://api.cauri.com/rest-{version}
- version: required(v1)
Flow
- Merchant calls method user/resolve for to determine the user id.
- User inputs and submits card data.
- Merchant calls method card/getToken via AJAX and receives a temporary token for 20 minutes.
- Merchant receives temporary token and other payment data on a server-side.
- Merchant calls method card/process with credit card token to create a card transaction.
- If success is true and acs object is returned:
- Merchant POSTs acs object parameters (PaReq, MD, TermUrl) to acs object url in a web browser.
- User inputs and submits his 3DSecure password.
- ACS POSTs parameters (PaRes, MD) back to merchant's acs return url.
- Merchant calls method card/authenticate passing PaRes and MD parameters to authenticates card transactions.
- If success is true that means that the merchant request has been accepted for processing.
- If success is false can not provide a service to a user.
- If success is true and acs object is not returned that means that the merchant request has been accepted for processing.
- If recurring was equal to 1, merchant will receive a recurring object, containing recurring profile token id, interval and endsAt parameters. Merchant can create new payments for a user calling the card/processRecurring method with recurring profile;
- If verify_card was equal to 1, then transaction price will be put on hold and then instantly returned. verify_card can be effectively used with recurring parameters as it checks the validity of a card via freezing and releasing funds on a card.
- If success is false can not provide a service to a user.
- Merchant receives asynchronous callback with transaction details and can provide a service to a user if status is completed.
Authentication
Request and callback parameters are signed to make sure the values can't be changed.
Rules to generate a signature:
Example parameters: ["n3rf34j96j8rge4", 123, "example@example.com"]
Sort parameter values ascending by value (case sensitive):
[123, "example@example.com", "n3rf34j96j8rge4"]
Concatenate parameter values with "|" (pipe):
123|example@example.com|n3rf34j96j8rge4
Hash it with a HMAC-SHA256 algorithm:
8c2c067121ff09c1444ad2bfc7b5b1af7c0c1d9dc89c805cd4c8c2b42a6c4f47
Signature PHP example
Example of function to generate a signature in PHP
function generate(array $parameters): string
{
sort($parameters, SORT_STRING);
return hash_hmac('sha256', implode('|', $parameters), 'PRIVATE_KEY');
}
Testing
At first you will get an account in sandbox mode. You can do almost everything with our system in this mode, but you can't manipulate with real money.
While your account is in sandbox mode you can only create test payments.
For testing aims you can use following bankcard numbers (for expiry time and security code you can use any valid values):
5444870724493746 - Success Bankcard without 3ds
6777060877427221 - Success Bankcard with 3ds
4012001038488884 - Unable to verify with 3ds Bankcard
4111111111111111 - Failing Bankcard
Merchant registries
You can receive a daily register for the previous day by email.
The email contains headers the following information:
X-Merchant-ID: 14 - Merchant ID assigned to a merchant.
X-Registry-Date: 2017-06-20 - Date for which the registry is created by UTC+0, in YYYY-MM-DD format.
From: registries@processing.cauri.com - You will receive letters from.
Subject: Cauri report for merchant #3 2017-06-20 - Cauri report for merchant #[Merchant ID] [YYYY-MM-DD].
Gate sends registries in the attachment in CSV format. The name of the file is registry-from-cauri-to-merchant-ID-YYYY-MM-DD, where:
ID – Your merchant id.
YYYY-MM-DD – Date for which the registry is created by UTC+0.
Registry is created in CSV format with UTF-8 encoding. The first line contains field names, ";" is used as column separator, each operation is included in the registry in a new line, to separate lines we use a Windows line separator symbol. The registry is sent even if there was not a single transaction for the past day. In this case, only the title bar is present in the message body.
Line format with information on payments:
Field name | Description and format | Example |
---|---|---|
Номер платежа | Identifier of a transaction by Cauri. | 1105 |
Номер заказа | Merchant's order id of a transaction. | 179 |
Номер возвращенного платежа | Identifier of a returned transaction if this is return transaction (type is equal to reversal or refund) | 1104 |
Дата и время платежа | The date and time the transaction was payed or failed in the ISO 8601 format. | 2017-05-15T08:47:05+00:00 |
E-mail плательщика | Payer's email | user@example.com |
Телефон плательщика | Payer's phone number if specified. (in international format, without the leading + and any separators). |
4401234567890 |
Тип операции | Operation type | payin, reversal, refund |
Наименование платёжной системы | Payment system name. (only 'bankcard' or 'test' value for now) |
bankcard, test |
Сумма платежа | Payment amount. (use decimal separator: «.») |
1.73 |
Сумма вознаграждения | Payment commission. (use decimal separator: «.») |
0.05 |
Комиссия за возврат | Return payment commission. (use decimal separator: «.») |
0.05 |
Код валюты | Currency code in the ISO 4217 alfa-3 format. | RUB, USD, EUR |
Transaction types
Type | Description |
---|---|
payin | Funds are charged from a user. |
return payin | Refund of payin transaction. Funds are returned to a user. |
redemption | Payment of money to the merchant. |
Transaction statuses
Status | Description |
---|---|
pending | The transaction is waiting for payment. |
authenticating | The transaction waiting for authenticate user on 3ds. |
paid | Transaction has completed successfully. |
fail | Transaction has failed. |
reversed | Transaction is reversed. |
refunded | Transaction is fully refunded. |
chargeback | Transaction is forcibly refunded due to dispute |
Errors
Error example
{
"error": {
"code": 40001,
"message": "Project's public key is missing."
}
}
List of errors
Message | Code | HTTP status code |
---|---|---|
Project's public key is missing. | 40001 | 400 Bad Request |
User's identifier is missing. | 40002 | 400 Bad Request |
The credit card number is missing. | 40003 | 400 Bad Request |
The credit card number is invalid. | 40004 | 400 Bad Request |
The credit card expiry is invalid. | 40005 | 400 Bad Request |
The credit card security code is missing. | 40006 | 400 Bad Request |
The credit card security code is invalid. | 40007 | 400 Bad Request |
Credit card token is missing. | 40008 | 400 Bad Request |
Credit card data is missing. | 40009 | 400 Bad Request |
User's email is missing. | 40010 | 400 Bad Request |
User's IP address is missing. | 40011 | 400 Bad Request |
The credit card expiration month is missing. | 40012 | 400 Bad Request |
The credit card expiration year is missing. | 40013 | 400 Bad Request |
Recurring profile is missing. | 40014 | 400 Bad Request |
Price is missing. | 40015 | 400 Bad Request |
Currency is missing. | 40016 | 400 Bad Request |
User's IP address is incorrect. | 40017 | 400 Bad Request |
Transaction's amount is incorrect. | 40018 | 400 Bad Request |
Permanent token is missing. | 40019 | 400 Bad Request |
Signature is missing. | 40101 | 401 Unauthorized |
Authentication token is missing. | 40102 | 401 Unauthorized |
Signature is invalid. | 40301 | 403 Forbidden |
Authentication token is invalid. | 40302 | 403 Forbidden |
Authentication token has expired. | 40303 | 403 Forbidden |
Credit card token has expired. | 40304 | 403 Forbidden |
Credit card token is already used. | 40305 | 403 Forbidden |
Platform authentication token is invalid. | 40306 | 403 Forbidden |
User is blocked. | 40308 | 403 Forbidden |
Credit card is blocked. | 40309 | 403 Forbidden |
Recurring is disabled for requested user. | 40310 | 403 Forbidden |
Recurring expired for requested user. | 40311 | 403 Forbidden |
Recurring profile has expired. | 40312 | 403 Forbidden |
Recurring profile is not active. | 40313 | 403 Forbidden |
Merchant can't use recurring profiles. | 40314 | 403 Forbidden |
Permanent token is not active. | 40315 | 403 Forbidden |
Project is missing. | 40401 | 404 Not Found |
Credit card token is invalid. | 40402 | 404 Not Found |
Transaction does not exist. | 40403 | 404 Not Found |
Platform is missing. | 40404 | 404 Not Found |
Reference recurrent transaction is missing. | 40405 | 404 Not Found |
User is missing. | 40406 | 404 Not Found |
Platform user is missing. | 40407 | 404 Not Found |
Recurring profile is invalid. | 40408 | 404 Not Found |
Transaction is already completed. | 40501 | 405 Method Not Allowed |
Recurring payments are too frequent for requested user. | 40502 | 405 Method Not Allowed |
Unable to create recurrent transaction. | 40503 | 405 Method Not Allowed |
Transaction cannot be reversed or refunded. | 40504 | 405 Method Not Allowed |
Payment is already reversed or refunded. | 40505 | 405 Method Not Allowed |
Price must be no less than 0.01. | 50001 | 500 Internal Server Error |
MD is incorrect. | 50002 | 500 Internal Server Error |
MD is empty. | 50003 | 500 Internal Server Error |
Currency cannot be blank. | 50004 | 500 Internal Server Error |
Currency is invalid. | 50005 | 500 Internal Server Error |
Price must be a number. | 50006 | 500 Internal Server Error |
Client requirements
Protocol | Support |
---|---|
TLS 1.3 | No |
TLS 1.2 | Yes |
TLS 1.1 | No |
TLS 1.0 | No |
SSL 3 | No |
SSL 2 | No |
SSL 1 | No |
Users
Creates a user if it doesn’t exist or returns an id of existing user.
Returns gate user id.
Card payments
Creates temporary bankcard token.
Returns token id to work with bankcard.
This method does not require a signature!
This method is intended for use on client-side.
Token expires in 20 minutes.
Creates and executes payment transaction.
Returns transaction id and bankcard information.
Performs 3d authentication on bankcard if it necessary.
Authenticates a bankcard using PaRes and MD parameters POST'ed back to acs return url from bank ACS.
Creates and executes payment transaction by recurring profile.
Returns transaction id and bankcard information.
Returns error 40314 if merchant can't use recurring profile.
Cancels recurring profile by id.
You will not be able to use this recurring profile after cancellation.
Transactions
Get transaction details and status.
Optional, either transaction id or order id is required!
While using order id in case if several transactions have the same order id, information about the last created transaction will be returned.
Returns error 40403 if transaction doesn’t exist.
Creates and executes reversal by transaction.
Optional, either transaction id or order id is required!
While using order id in case if several transactions have the same order id, the last created transaction will be reversed.
Creating a money return of this type is possible only if the transaction status request returns can reverse is true.
Returns error 40403 if transaction doesn’t exist, 40504 if transaction cannot be reversed/refunded and 40505 if payment is already reversed/refunded.
Creates and executes refund by transaction.
Optional, either transaction id or order id is required!
While using order id in case if several transactions have the same order id, the last created transaction will be refunded.
Creating a money return of of this type is possible only if the transaction status request returns can refund is true.
Returns error 40403 if transaction doesn’t exist, 40504 if transaction cannot be reversed/refunded and 40505 if payment is already reversed/refunded.
Merchant callback
You will receive the callback parameters via HTTP POST method.
Replace __CALLBACK_URL__ from example with your merchant’s callback URL. You can validate callback signature from example against the test private key 25c28f39df289bb9ab207ed2030c4c35.
Callback URL can be set in merchant settings.
If the callback URL replies with an HTTP status other than 200, gate tries to call it during twenty-four hours.