Actions

Test request (GET /ping)

Parameters

Name	Description	Example
message	Message	PONG!
date	Current date and time on the server	2016-06-30 14:09:20

Status represents the final result of processing the operation

Status represents the current order state

Response

Example

Fetching data

When fetching data such as a list of orders, the number of rows in response is limited to 2000 per page. Please use some filters to narrow the search. Follow links in HTTP headers to scroll through pages.

Order information (GET /orders/:id)

Parameters

Name	Description	Example
expand	MessagList of extra objects to display. Possible expands are: card, client, location, custom_fields, issuer, secure3d, operations.cashflow	card, location, client

Response

Example

List of orders (GET /orders/)

Optional parameters

Name	Description	Example
expand	List of extra objects to display. Possible expands are: card, client, location, custom_fields, issuer, secure3d, operations.cashflow	card,location,client
status	Filter by status	charged,refunded
created_from	Filter by date of creation	2016-01-01 00:00:00
created_to	Filter by date of creation	AUTH12016-01-31 23:59:59
merchant_order_id	Filter by merchant order ID	12345,123456
card.type	Filter by card type	visa,mastercard
card.subtype	Filter by card subtype	electron,maestro
location.ip	Filter by IP address	8.8.8.8,8.8.8.9
client.name	Find by client name or part of it	Smith
client.email	Find by email or part of it	@yahoo.com
issuer.country	Filter by issuer country (ISO 3166-1 alpha-3)	USA
issuer.bin	Filter by issuer BIN	555555,411111
issuer.title	Find by issuer name or part of it	Credit Union

Response

Example

List of operations (GET /operations/)

Optional parameters

Name	Description	Example
expand	List of extra objects to display. Possible expand is cashflow, extra	cashflow
status	Filter by status	error
type	Filter by type	charge,refund
created_from	Filter by date of creation	2016-01-01 00:00:00
created_to	Filter by date of creation	2016-01-31 23:59:59

Response

Example

Notes - trace_id will be displayed only if this option is enabled in the system.

Export of currency rates (GET /exchange_rates/)

Parameters

Name	Description	Example
expand	List of extra objects to display. Possible expand is cashflow, extra	cashflow
status	Filter by status	error
type	Filter by type	charge,refund
created_from	Filter by date of creation	2016-01-01 00:00:00
created_to	Filter by date of creation	2016-01-31 23:59:59

Response

Example

Notes - Filters by date and date period cannot be used at the same time.

Working with orders

Order creation (POST /orders/create)

The success response on this request is returned with response code 201. It means that the new order is created and it is waiting for input from cardholder.

Required parameters

Name	Description	Description
amount	Order amount	9.99

Optional parameters

Response

Example (only required fields provided)

curl -v -X POST -H 'Content-Type: application/json' -d '{
"amount" : 9.99
}' '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: 15
>
< Location: http://localhost:5002/pay/23014805213622230
< Content-Type: application/json
< Content-Length: 341
<

{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "0.00",
      "amount_refunded": "0.00",
      "card": {},
      "client": {},
      "created": "2016-08-22 15:39:42",
      "currency": "USD",
      "custom_fields": {},
      "description": null,
      "id": "23014805213622230",
      "issuer": {},
      "location": {},
      "merchant_order_id": null,
      "operations": [],
      "secure3d": {},
      "status": "new",
      "updated": "2016-08-22 15:39:42"
    }
  ]
}

Example (all the fields provided)

To manage the inclusion of Google Pay™ and Apple Pay on the checkout page using flags *_pay_enabled must be disabled global support in the

settings.

Creating a static link must be enabled in the settings.

Authorize (POST /orders/authorize)

The success response on this request may be returned with response code 200 or 201.

Code 201 means that the order is prepared for the 3-D Secure authentication and it is waiting for cardholder to return from ACS. You should make the

cardholder submit the HTML-form provided in response.

Code 200 means that the authorization is complete. This happens in cases when 3-D Secure was not requested or authentication was completed without

cardholder participation.

Required parameters

Name	Description	Example
amount	Order amount	9.99
pan	Card number (PAN)	4111111111111111
card	Card details (*)	-
*.cvv	CVV-code (can be configured as optional in project settings)	123
*.holder	Cardholder name (can be configured as optional in project settings, from 2 to 40 characters)	John Smith
*.expiration_month	Month of the card expiration date	06
*.expiration_year	Year of the card expiration date	2024
location	Client location details (*)	-
*.ip	IP-address	8.8.8.8

Optional parameters

Response

Examples

Example (only required fields provided)

curl -v -X POST -H 'Content-Type: application/json' -d '{
"amount" : 9.99,
"card" : {
"cvv" : "333",
"expiration_month" : 12,
"expiration_year" : 2020,
"holder" : "John Smith"
},
"location" : {
"ip" : "6.6.6.6"
},
"pan" : "4111111111111111"
}' 'http://project:***@api.box:5001/orders/authorize'
> POST /orders/authorize HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
> Content-Length: 156
>
< Content-Type: application/json
< Content-Length: 829
<

{
   "orders":[
      {
         "amount":"9.99",
         "amount_charged":"0.00",
         "amount_refunded":"0.00",
         "auth_code":"AUTH12",
         "card":{
            "holder":"John Smith",
            "subtype":"classic",
            "type":"visa"
         },
         "client":{
            
         },
         "created":"2016-08-22 15:39:48",
         "currency":"USD",
         "custom_fields":{
            
         },
         "description":null,
         "descriptor":"TESTMERCH/TERM",
         "id":"23014806643308174",
         "issuer":{
            "bin":"411111",
            "country":"UKR",
            "title":"TestBank"
         },
         "location":{
            "ip":"6.6.6.6"
         },
         "merchant_order_id":null,
         "operations":[
            {
               "amount":"9.99",
               "auth_code":"AUTH12",
               "cashflow":{
                  "amount":"0.00",
                  "currency":"USD",
                  "fee":"0.00",
                  "incoming":"0.00",
                  "receivable":"0.00",
                  "reserve":"0.00"
               },
               "created":"2016-08-22 15:39:48",
               "currency":"USD",
               "iso_message":"Approved",
               "iso_response_code":"00",
               "status":"success",
               "type":"authorize"
            }
         ],
         "pan":"411111****1111",
         "secure3d":{
            
         },
         "status":"authorized",
         "updated":"2016-08-22 15:39:48"
      }
   ]
}

Example (all fields provided)

Example (3-D Secure)

Once the authorization request is completed, it has to be followed with Charge operation. It also can be can be done with auto_charge option passed in

request or automatically depending on project settings.

If charge is never processed, authorization will be released by the card issuer after some time and

authorized amount will be available back to the cardholder.

Reverse (PUT /orders/:id/reverse)

Parameters

Not supported.

Response

Example

Charge (PUT /orders/:id/charge)

Parameters

Name	Description	Example
amount	Amount of charge	9.99

Responce

Example (full charge)

Example (partial charge)

Refund (PUT /orders/:id/refund)

Parameters

Name	Description	Example
amount	Amount of refund	9.99

Response

Example (full refund)

Example (partial refund)

Cancel (PUT /orders/:id/cancel)

This is the equivalent of making Reverse or Refund depending on current order state.

Parameters

Name	Description	Example
amount	Amount of refund (not applicable for reversing)	9.99

Response

Example

Repeating payment (POST /orders/:id/rebill)

Required parameters

Name	Description	Example
amount	Amount	9.99
cvv	CVV-code (can be configured as optional in project settings)	123
location	Client location details (*)	-
*.ip	IP-address	8.8.8.8

Optional parameters

Response

Example

Original credit transaction (OCT) (POST /orders/:id/credit)

Required parameters

Name	Description	Example
amount	Amount	9.99

Optional parameters

Response

Example

Original credit transaction without link to order (OCT) (POST /orders/credit)

Required parameters

Name	Description	Example
amount	Amount	9.99
pan	Card number (PAN)	4111111111111111

Optional parameters

Response

Example

Authorization with the transfer of an encrypted token ( POST /orders/token_pay)

Required parameters

amount	Amount	9.99
dsrp	DSRP data (*)	-
*.type	Token type	apple_pay
*.token	DSRP token	eyJwYXltZW50RGF0YS...kljcEJhOTR WTi9KVGdhOFc3NUlXQUE9PSJ9fQ==
location	Client location details (*)	-
*.ip	IP-address	8.8.8.8

Example

Endpoint is transfered encrypted token of Google Pay or Apple Pay. Allowed field values type: google_pay, apple_pay. Optional parameters are the

same as for Authorize, except fields pan, card.*, secure3d.*, options.force3d, options.return_url, options.secure3d20_return_url.

Completion of 3-D Secure Authentication (POST /orders/:id/complete)

Required parameters

Name	Description	Example
PaRes	Payer authentication response	424EF64895CAE9797497F

Example

The endpoint sends a response to the authorization request. When resubmitting the request to the endpoint the answer will be received: "Order already

completed".

Completion of 3-D Secure 2.0 Authentication (POST /orders/:id/complete3d20)

Optional parameters

Name	Description	Example
cres	Base64 encoded string containing the results of 3-D Secure authentication	ewogICJhY3NUcmFuc0...W9uIiA6ICIyLjEuMCIKfQ==

Response

Example

The endpoint completes authorization performed with 3-D Secure 2.0 authentication. If there is no data in the order properties identification from RReq, a

validation error will be received and order will remain in the prepare status.

Continue 3DS Method URL of authentication (POST /orders/:id/resume)

Parameters

Not supported

Response

Example

The endpoint continues the authorization described in Payments with 3-D Secure 2.0. Maximum time waiting for a response to a request - 10 seconds