API overview

General information

• Requests are made through HTTP 1.1 using SSL and Basic-Authentication.

• Requests and responses are encoded in UTF-8.

• Requests and responses are JSON structures.

• When getting information use the method GET, when manipulation with data methods POST or PUT is required.

• In GET-requests parameters are passed as QUERY STRING.

• In POST-requests parameters are passed as a body of the POST-request, in some cases QUERY STRING could be used too.

• Success responses are sent with aHTTP-status 200 or 201. In case of an error, the status may vary (see Response codes).

(1) Authentication

API uses Basic-Authentication. Login and password should be passed every time you send a request to API.

GET /orders/ HTTP/1.1
Authorization: Basic Zm9vOmJhcg==
Host: example.com

(2) Response codes

HTTP response code describes the result of the requested operation, as follows:

Code	Description
200	This code means the operation you requested has been processed successfully. Depending on which operation you have requested, it may tell that authorization, reversal, charge or refund has been made
201	An order has been created and it is waiting for additional input
402	The operation has been declined by the acquirer or rejected by the gateway
422	Request validation failed
500	Error on the acquirer or gateway side

(3) Failure type

HTTP response code describes the result of the requested operation, as follows:

Code	Description
declined	The acquirer has declined the transaction
fraud	The transaction has been declined by fraud prevention rules on the gateway side
rejected	The transaction has been declined by the gateway
error	Failure due to an error on the acquirer or gateway side
validation	The request was not processed because of incorrect input

(4) Working flow

Verifying successful operation

The successful response always returned with the code 200, details of an order are in the response body. To ensure that you have completed the operation, it is necessary and sufficient to check the response code and order status in the response body.

All errors are returned as a standard failure response, an error message can be found in the response body:

(4.1.) Error handling

All errors are returned as a standard failure response, an error message can be found in the response body:

{
    "failure_type" : "error",
    "failure_message" : "This is an error",
    "order_id" : null,
}

Description of an error is located in a failure_message field. If there is an order created during a request, its identifier is returned in an order_id field.

(4.2.) Processing declined transactions

All responses for transactions declined by the issuer are returned in a uniform format:

{
    "failure_message":"Soft-Decline",
    "order_id":"123456789", 
    "failure_type":"declined"
}

The principle for forming a response is the same as for handling errors. If authorization is rejected according to the Soft-Decline scenario, it means that the request parameters are not meet the normative of SCA (Strong Customer Authentication). Such authorization must be done with the force3d flag.

In the order information for Soft-Decline, iso_response_code will be A1.

(4.3.) Validation

In case of a validation error, there is an extra field error returned which contains the list of incorrect parameters and some extra information.

Example:

curl -v -X POST -H 'Content-Type: application/json' -d '{ "foo" : "bar"
}' 'http://project:***@api.box:5001/orders/create'

> POST /orders/create HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
> Content-Length: 13 
>
< HTTP/1.1 422 Unprocessable Entity
< Content-Type: application/json
< Content-Length: 223 
<

{ "errors" : [ { "attribute" : "required", "details" : [ "(true)" ], "message" : "Required", "uri" : "#/amount" }, { "message" : "Unknown property", "uri" : "#/foo" } ], "failure_message" : "Validation failed", "failure_type" : "validation", "order_id" : null }

(4.4.) Sample code

response = http.post('https://api/authorize', pan => 4111111111111111, ... , cvv => 123);

if response.code == 200 {
    order = decode_json(response.body);
    
    print "Authorization success"; 
    print "Order ID: " . order.id
} else if response.code == 402 {

    print "Authorization declined";
    print "Decline reason: " . response.failure_message;
    
} else if response.code == 422 {

    print "Input data is incorrect";
    print "Reason: " . response.failure_message;
    
} else {

print "An error occured: " . response.failure_message; 
}

{ "errors" : [ { "attribute" : "required", "details" : [ "(true)" ], "message" : "Required", "uri" : "#/amount" }, { "message" : "Unknown property", "uri" : "#/foo" } ], "failure_message" : "Validation failed", "failure_type" : "validation", "order_id" : null }