Actions

Test request (GET /ping)

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

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)

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

List of orders (GET /orders/)

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

List of operations (GET /operations/)

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

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

Export of currency rates (GET /exchange_rates/)

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

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.

Name
Description
Description

amount

Order amount

9.99

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"
    }
  ]
}

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.

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

Examples

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"
      }
   ]
}

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)

Not supported.

Charge (PUT /orders/:id/charge)

Name
Description
Example

amount

Amount of charge

9.99

Refund (PUT /orders/:id/refund)

Name
Description
Example

amount

Amount of refund

9.99

Cancel (PUT /orders/:id/cancel)

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

Name
Description
Example

amount

Amount of refund (not applicable for reversing)

9.99

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

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

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

Name
Description
Example

amount

Amount

9.99

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

Name
Description
Example

amount

Amount

9.99

pan

Card number (PAN)

4111111111111111

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

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

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)

Name
Description
Example

PaRes

Payer authentication response

424EF64895CAE9797497F

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)

Name
Description
Example

cres

Base64 encoded string containing the results of 3-D

Secure authentication

ewogICJhY3NUcmFuc0...W9uIiA6ICIyLjEuMCIKfQ==

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)

Not supported

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

Last updated