# Actions

## <mark style="color:blue;">Test request (GET /ping)</mark>

{% tabs %}
{% tab title="Parameters" %}

<table><thead><tr><th width="121">Name</th><th width="420">Description</th><th>Example</th></tr></thead><tbody><tr><td>message</td><td>Message</td><td>PONG!</td></tr><tr><td>date</td><td>Current date and time on the server</td><td>2016-06-30 14:09:20</td></tr></tbody></table>

Status represents the final result of processing the operation

Status represents the current order state
{% endtab %}

{% tab title="Response" %}

{% endtab %}

{% tab title="Example" %}

```json
curl -v -X GET -H 'Content-Type: application/json' 'http://project:***@api.box:5001/ping'

> GET /ping HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json 
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 48 
<
```

```json
{
  "date": "2016-08-22 15:39:42",
  "message": "PONG!"
}
```

{% endtab %}
{% endtabs %}

## Fetching data

{% hint style="info" %}
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.
{% endhint %}

### <mark style="color:blue;">Order information (GET /orders/:id)</mark>

{% tabs %}
{% tab title="Parameters" %}

<table><thead><tr><th width="110">Name</th><th width="592">Description</th><th>Example</th></tr></thead><tbody><tr><td>expand</td><td>MessagList of extra objects to display. Possible expands are: card, client, location, custom_fields, issuer, secure3d, operations.cashflow</td><td>card, location, client</td></tr></tbody></table>
{% endtab %}

{% tab title="Response" %}

| Status                   | Possible operations | Description                                                                                  |
| ------------------------ | ------------------- | -------------------------------------------------------------------------------------------- |
| amount                   | 9.99                | Order amount                                                                                 |
| amount\_charged          | 9.99                | Charged amount                                                                               |
| amount\_refunded         | 5.99                | Refunded amount                                                                              |
| auth\_code               | AUTH12              | Authorization code                                                                           |
| card                     | -                   | Card details (\*)                                                                            |
| \*.holder                | John Smith          | Cardholder name                                                                              |
| \*.subtype               | classic             | Card subtype                                                                                 |
| \*.type                  | visa                | Card type                                                                                    |
| client                   | -                   | Client details (\*)                                                                          |
| \*.address               | Main ave. 1         | Street address                                                                               |
| \*.city                  | San Francisco       | City                                                                                         |
| \*.country               | USA                 | Country                                                                                      |
| \*.email                 | <foo@bar.com>       | E-mail                                                                                       |
| \*.name                  | John Smith          | Full name                                                                                    |
| \*.phone                 | +14568901231        | Phone number                                                                                 |
| \*.state                 | CA                  | State                                                                                        |
| \*.zip                   | 12345               | Postal code                                                                                  |
| \*.login                 | john\_doe           | Login                                                                                        |
| created                  | 2014-06-30 14:38:48 | Creation date and time                                                                       |
| currency                 | USD                 | Requested payment currency (ISO-4217 3-alpha code)                                           |
| description              | Book sale #453      | Order description                                                                            |
| descriptor               | EXAMPLE.COM/12345   | Terminal Descriptor                                                                          |
| id                       | 5673044075769513    | Unique order ID                                                                              |
| issuer                   | -                   | Card issuer details                                                                          |
| \*.bin                   | 411111              | BIN                                                                                          |
| \*.country               | RUS                 | Country (ISO 3166-1 alpha-3)                                                                 |
| \*.title                 | Bank                | Bank name                                                                                    |
| location                 | -                   | Client location details (\*)                                                                 |
| \*.country               | USA                 | Country (ISO 3166-1 alpha-3)                                                                 |
| \*.city                  | San Francisco       | City                                                                                         |
| \*.region                | California          | Region                                                                                       |
| \*.ip                    | 8.8.8.8             | IP-address                                                                                   |
| merchant\_order\_id      | 5678                | Merchant's order ID                                                                          |
| operations               | -                   | Array of the order operations (\*). See the description of fields in the List— of operations |
| pan                      | 411111\*\*\*\*1111  | Card number (PAN)                                                                            |
| secure3d                 | -                   | 3-D Secure details (\*)                                                                      |
| \*.reason                | force               | The reason why 3-D Secure was enabled                                                        |
| \*.scenario              | full                | 3-D Secure scenario used                                                                     |
| \*.authorization\_status | Y                   | Status of authorization                                                                      |
| segment                  | 987654321           | Segment                                                                                      |
| status                   | authorized          | Order Status                                                                                 |
| updated                  | 2014-06-30 14:38:48 | Date and time of the last operation                                                          |
| {% endtab %}             |                     |                                                                                              |

{% tab title="Example" %}

```graphql
curl -v -X GET -H 'Content-Type: application/json' 'http://project:***@api.box:5001/orders/65213580296542862? 
expand=card,client,location,custom_fields,issuer,secure3d,operations.cashflow'

> GET /orders/23014806815093624?expand=card,client,location,custom_fields,issuer,secure3d,operations.cashflow HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 1018 <
{
"orders" : [ 
    {
        "amount" : "9.99", 
        "amount_charged" : "0.00",
        "amount_refunded" : "0.00", 
        "auth_code" : "AUTH12", 
        "card" : {
            "holder" : "John Smith", 
            "subtype" : "classic", 
            "type" : "visa"
        },
        "client" : {
            "address" : "Main ave. 1",
            "city" : "San Francisco", 
            "country" : "USA",
            "email" : "foo@bar.com", 
            "name" : "John Smith", 
            "phone" : "+1 456 890", 
            "state" : "CA",
            "zip" : "123456" 
        },
        "created" : "2021-11-12 12:16:13",
        "currency" : "USD", 
        "custom_fields" : {}, 
        "description" : "Book sale #453", 
        "descriptor" : "TESTMERCH/TERM", 
        "id" : "65213580296542862", 
        "issuer" : {
        "bin" : "411111",
            "country" : "UKR", 
            "title" : "TestBank"
        },
        "location" : {
            "ip" : "6.6.6.6" 
        },
        "merchant_order_id" : "5678", 
        "operations" : [
            {
                "type": "authorize",
                "iso_message": "Approved", 
                "created": "2021-11-12 12:16:13", 
                "amount": "1213.00",
                 "auth_code": "212636", 
                "iso_response_code": "00", 
                "cashflow": {
                "incoming": "0.00", 
                "fee": "0.00", 
                "receivable": "-36.39", 
                "amount": "0.00", 
                "currency": "USD", 
                "reserve": "36.39"
            },
            "currency": "USD", 
            "status": "success"
            }, 
            {
                "currency": "USD",
                "status": "success", 
                "cashflow": {
                "receivable": "1164.48", 
                "amount": "1213.00", 
                "reserve": "36.39", 
                "currency": "USD", 
                "incoming": "1200.87", 
                "fee": "12.13"
            },
            "arn": "73922059535879175995901", 
            "iso_response_code": "00", 
            "iso_message": "Approved", 
            "created": "2021-11-12 12:21:13", 
            "amount": "1213.00",
            "type": "charge"
        } 
        ],
        "pan" : "411111****1111", 
        "secure3d" : {},
        "segment" : "987654321",
        "status" : "authorized", 
        "updated" : "2016-08-22 15:39:49"
        } 
    ]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">List of orders (GET /orders/)</mark>

{% tabs %}
{% tab title="Optional parameters" %}

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

{% tab title="Response" %}
All the fields are the same as described in the [**Order information**](#order-information-get-orders-id)**.**
{% endtab %}

{% tab title="Example" %}

```json
curl -v -X GET -H 'Content-Type: application/json' 'http://project:***@api.box:5001/orders/'

> GET /orders/ HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json 
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 5550 
<
```

```json
{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "0.00",
      "amount_refunded": "0.00",
      "auth_code": "AUTH12",
      "created": "2016-08-22 15:39:49",
      "currency": "USD",
      "description": "Book sale #453",
      "descriptor": "TESTMERCH/TERM",
      "id": "23014806815093624",
      "merchant_order_id": "5678",
      "pan": "411111****1111",
      "segment": "987654321",
      "status": "authorized",
      "updated": "2016-08-22 15:39:49"
    },
    {
      "amount": "9.99",
      "amount_charged": "0.00",
      "amount_refunded": "0.00",
      "auth_code": "AUTH12",
      "created": "2016-08-22 15:39:48",
      "currency": "USD",
      "description": null,
      "descriptor": "TESTMERCH/TERM",
      "id": "23014806643308174",
      "merchant_order_id": null,
      "pan": "411111****1111",
      "status": "authorized",
      "updated": "2016-08-22 15:39:48"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">List of operations (GET /operations/)</mark>

{% tabs %}
{% tab title="Optional parameters" %}

<table><thead><tr><th width="149">Name</th><th width="406">Description</th><th>Example</th></tr></thead><tbody><tr><td>expand</td><td>List of extra objects to display. Possible expand is cashflow, extra</td><td>cashflow</td></tr><tr><td>status</td><td>Filter by status</td><td>error</td></tr><tr><td>type</td><td>Filter by type</td><td>charge,refund</td></tr><tr><td>created_from</td><td>Filter by date of creation</td><td>2016-01-01 00:00:00</td></tr><tr><td>created_to</td><td>Filter by date of creation</td><td>2016-01-31 23:59:59</td></tr></tbody></table>
{% endtab %}

{% tab title="Response" %}

<table><thead><tr><th width="188">Name</th><th width="368">Description</th><th>Example</th></tr></thead><tbody><tr><td>amount</td><td>Operation amount</td><td>9.99</td></tr><tr><td>auth_code</td><td>Authorization code</td><td>AUTH12</td></tr><tr><td>created</td><td>Operation date and time</td><td>2014-06-30 14:38:48</td></tr><tr><td>currency</td><td>Requested payment currency (ISO-4217 3-alpha code)</td><td>USD</td></tr><tr><td>iso_message</td><td>Response message</td><td>Approved</td></tr><tr><td>iso_response_code</td><td>Response ISO-code</td><td>00</td></tr><tr><td>status</td><td>Operation status</td><td>success</td></tr><tr><td>type</td><td>Operation type</td><td>authorize</td></tr><tr><td>trace_id</td><td>Trace ID</td><td>MCC8454300719</td></tr><tr><td>cashflow</td><td>Financial details (*)</td><td>-</td></tr><tr><td>*.currency</td><td>Accounting currency (ISO-4217 3-alpha code)</td><td>EUR</td></tr><tr><td>*.amount</td><td>Accounting amount</td><td>9.00</td></tr><tr><td>*.fee</td><td>Fee amount</td><td>0.00</td></tr><tr><td>*.incoming</td><td>Income amount</td><td>6.00</td></tr><tr><td>*.receivable</td><td>Receivable amount</td><td>5.00</td></tr><tr><td>*.reserve</td><td>Reserved amount</td><td>0.00</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```
curl -v -X GET -H 'Content-Type: application/json' 'http://project:***@api.box:5001/operations/'

> GET /operations/ HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json 
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 2931 
<
{
    "operations" : [ 
        {
            "amount" : "11991.00",
            "auth_code" : "AUTH12",
            "created" : "2016-08-24 12:07:00", 
            "currency" : "EUR",
            "iso_message" : "Approved", 
            "iso_response_code" : "00", 
            "order_id" : "23011537206894183", 
            "arn": "28281615742473953725862", 
            "status" : "success",
            "type" : "charge"
        },
        {
            "amount" : "8997.00",
            "auth_code" : "AUTH12",
            "created" : "2016-08-23 12:06:55", 
            "currency" : "USD",
            "iso_message" : "Approved", 
            "iso_response_code" : "00", 
            "order_id" : "23011536237676397", 
            "status" : "success",
            "type" : "authorize"
        } 
    ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Notes *- trace\_id* will be displayed only if this option is enabled in the system.
{% endhint %}

### <mark style="color:blue;">Export of currency rates (GET /exchange\_rates/)</mark>

{% tabs %}
{% tab title="Parameters" %}

<table><thead><tr><th width="149">Name</th><th width="406">Description</th><th>Example</th></tr></thead><tbody><tr><td>expand</td><td>List of extra objects to display. Possible expand is cashflow, extra</td><td>cashflow</td></tr><tr><td>status</td><td>Filter by status</td><td>error</td></tr><tr><td>type</td><td>Filter by type</td><td>charge,refund</td></tr><tr><td>created_from</td><td>Filter by date of creation</td><td>2016-01-01 00:00:00</td></tr><tr><td>created_to</td><td>Filter by date of creation</td><td>2016-01-31 23:59:59</td></tr></tbody></table>

{% endtab %}

{% tab title="Response" %}

<table><thead><tr><th width="188">Name</th><th width="368">Description</th><th>Example</th></tr></thead><tbody><tr><td>amount</td><td>Operation amount</td><td>9.99</td></tr><tr><td>auth_code</td><td>Authorization code</td><td>AUTH12</td></tr><tr><td>created</td><td>Operation date and time</td><td>2014-06-30 14:38:48</td></tr><tr><td>currency</td><td>Requested payment currency (ISO-4217 3-alpha code)</td><td>USD</td></tr><tr><td>iso_message</td><td>Response message</td><td>Approved</td></tr><tr><td>iso_response_code</td><td>Response ISO-code</td><td>00</td></tr><tr><td>status</td><td>Operation status</td><td>success</td></tr><tr><td>type</td><td>Operation type</td><td>authorize</td></tr><tr><td>trace_id</td><td>Trace ID</td><td>MCC8454300719</td></tr><tr><td>cashflow</td><td>Financial details (*)</td><td>-</td></tr><tr><td>*.currency</td><td>Accounting currency (ISO-4217 3-alpha code)</td><td>EUR</td></tr><tr><td>*.amount</td><td>Accounting amount</td><td>9.00</td></tr><tr><td>*.fee</td><td>Fee amount</td><td>0.00</td></tr><tr><td>*.incoming</td><td>Income amount</td><td>6.00</td></tr><tr><td>*.receivable</td><td>Receivable amount</td><td>5.00</td></tr><tr><td>*.reserve</td><td>Reserved amount</td><td>0.00</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```
curl -v -X GET -H 'Content-Type: application/json' 'http://project:***@api.box:5001/operations/'

> GET /operations/ HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json 
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 2931 
<
{
    "operations" : [ 
        {
            "amount" : "11991.00",
            "auth_code" : "AUTH12",
            "created" : "2016-08-24 12:07:00", 
            "currency" : "EUR",
            "iso_message" : "Approved", 
            "iso_response_code" : "00", 
            "order_id" : "23011537206894183", 
            "arn": "28281615742473953725862", 
            "status" : "success",
            "type" : "charge"
        },
        {
            "amount" : "8997.00",
            "auth_code" : "AUTH12",
            "created" : "2016-08-23 12:06:55", 
            "currency" : "USD",
            "iso_message" : "Approved", 
            "iso_response_code" : "00", 
            "order_id" : "23011536237676397", 
            "status" : "success",
            "type" : "authorize"
        } 
    ]
}
```

```json
{
  "exchange_rates": [
    {
      "from": "EUR",
      "rate": "75.132109",
      "to": "RUB"
    },
    {
      "to": "UAH",
      "from": "EUR",
      "rate": "31.562887"
    },
    {
      "from": "EUR",
      "rate": "334.000000",
      "to": "UBT"
    },
    {
      "to": "USD",
      "from": "EUR",
      "rate": "1.145036"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Notes *-* Filters by date and date period cannot be used at the same time.
{% endhint %}

## Working with orders

### <mark style="color:blue;">Order creation (POST /orders/create)</mark>

{% hint style="warning" %}
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.
{% endhint %}

{% tabs %}
{% tab title="Required parameters" %}

| Name         | Description  | Description |
| ------------ | ------------ | ----------- |
| amount       | Order amount | 9.99        |
| {% endtab %} |              |             |

{% tab title="Optional parameters" %}

| Name                       | Description                                                                               | Example             |
| -------------------------- | ----------------------------------------------------------------------------------------- | ------------------- |
| currency                   | Order currency                                                                            | USD                 |
| merchant\_order\_id        | Merchant's order ID                                                                       | 5678                |
| segment                    | Segment                                                                                   | 987654321           |
| description                | Order description                                                                         | Book sale #453      |
| client                     | Client details (<mark style="color:orange;">\*</mark>)                                    | -                   |
| \*.address                 | Street address                                                                            | Main ave. 1         |
| \*.city                    | City                                                                                      | San Francisco       |
| \*.country                 | Country (ISO 3166-1 alpha-3)                                                              | USA                 |
| \*.email                   | E-mail                                                                                    | <foo@bar.com>       |
| \*.name                    | Full name                                                                                 | John Smith          |
| \*.phone                   | Phone number                                                                              | +1 456 890          |
| \*.state                   | State                                                                                     | CA                  |
| \*.zip                     | Postal code                                                                               | 123456              |
| \*.login                   | Login                                                                                     | john\_doe           |
| custom\_fields             | Additional custom fields (\*), up to 10 additional values                                 | -                   |
| location                   | Client location details (<mark style="color:orange;">\*</mark>)                           | -                   |
| \*.ip                      | IP-address                                                                                | 8.8.8.8             |
| options                    | Options (<mark style="color:orange;">\*</mark>)                                           | -                   |
| \*.expiration\_timeout     | Session expiration timeout                                                                | 30m                 |
| \*.force3d                 | Forced 3-D Secure verification                                                            | 1                   |
| \*.auto\_charge            | Executes Charge operation (is used for 1-stage payments)                                  | 1                   |
| \*.language                | Payment page language                                                                     | en                  |
| \*.return\_url             | <mark style="color:orange;">URL</mark> to redirect customer when the payment is completed | <http://my.url>     |
| \*.template                | Payment page layout                                                                       | 12                  |
| \*.mobile                  | Mobile layout                                                                             | 1                   |
| \*.terminal                | Terminal                                                                                  | TERM12              |
| \*.apple\_pay\_enabled     | Apple Pay support on checkout page                                                        | 1                   |
| \*.google\_pay\_enabled    | Google Pay™ support on checkout page                                                      | 1                   |
| \*.secure3d20\_return\_url | Notification <mark style="color:orange;">URL</mark> 3-D Secure 2.0                        | <http://return.url> |
| \*.exemption\_mit          | Exemption MIT flag                                                                        | 1                   |
| \*.static\_link            | Static link flag                                                                          | 1                   |
| {% endtab %}               |                                                                                           |                     |

{% tab title="Response" %}
Fields in response are the same as described in [Order information.](#order-information-get-orders-id)

HTTP-header Location contents a URL of a payment page. Please redirect the cardholder to this URL.
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Example (only required fields provided)" %}

```graphql
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
<
```

```json
{
  "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"
    }
  ]
}
```

{% endtab %}

{% tab title="Example (all the fields provided)" %}

```graphql
curl -v -X POST -H 'Content-Type: application/json' -d '{
"amount" : 9.99,
"client" : {
"address" : "Main ave. 1",
"city" : "San Francisco",
"country" : "USA",
"email" : "foo@bar.com",
"name" : "John Smith",
"phone" : "+1 456 890",
"state" : "CA",
"zip" : "123456"
},
"description" : "Book sale #453",
"location" : {
"ip" : "6.6.6.6"
},
"merchant_order_id" : "5678",
"options" : {
"force3d" : 0,
"return_url" : "http://shop.com",
"terminal" : ""
},
"segment" : "987654321"
}' '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: 357
>
< HTTP/1.1 201 Created
< Location: http://localhost:5002/pay/23014805439541518
< Content-Type: application/json
< Content-Length: 544
<
```

```json
{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "0.00",
      "amount_refunded": "0.00",
      "card": {},
      "client": {
        "address": "Main ave. 1",
        "city": "San Francisco",
        "country": "USA",
        "email": "foo@bar.com",
        "name": "John Smith",
        "phone": "+1 456 890",
        "state": "CA",
        "zip": "123456"
      },
      "created": "2016-08-22 15:39:43",
      "currency": "USD",
      "custom_fields": {},
      "description": "Book sale #453",
      "id": "23014805439541518",
      "issuer": {},
      "location": {
        "ip": "6.6.6.6"
      },
      "merchant_order_id": "5678",
      "operations": [],
      "secure3d": {},
      "segment": "987654321",
      "status": "new",
      "updated": "2016-08-22 15:39:43"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

### <mark style="color:blue;">Authorize (POST /orders/authorize)</mark>

{% hint style="warning" %}
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.
{% endhint %}

{% tabs %}
{% tab title="Required parameters" %}

| Name                 | Description                                                                                               | Example          |
| -------------------- | --------------------------------------------------------------------------------------------------------- | ---------------- |
| amount               | Order amount                                                                                              | 9.99             |
| pan                  | Card number (PAN)                                                                                         | 4111111111111111 |
| card                 | Card details (<mark style="color:orange;">\*</mark>)                                                      | -                |
| \*.cvv               | CVV-code (can be configured as optional in project settings)                                              | 123              |
| \*.holder            | <p>Cardholder name (can be configured as optional in project settings,</p><p>from 2 to 40 characters)</p> | John Smith       |
| \*.expiration\_month | Month of the card expiration date                                                                         | 06               |
| \*.expiration\_year  | Year of the card expiration date                                                                          | 2024             |
| location             | Client location details (<mark style="color:orange;">\*</mark>)                                           | -                |
| \*.ip                | IP-address                                                                                                | 8.8.8.8          |
| {% endtab %}         |                                                                                                           |                  |

{% tab title="Optional parameters" %}

| Name                       | Description                                                                               | Example                                    |
| -------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------ |
| currency                   | Order currency                                                                            | USD                                        |
| merchant\_order\_id        | Merchant's order ID                                                                       | 5678                                       |
| segment                    | Segment                                                                                   | 987654321                                  |
| description                | Order description                                                                         | Book sale #453                             |
| client                     | Client details (<mark style="color:orange;">\*</mark>)                                    | -                                          |
| \*.address                 | Street address                                                                            | Main ave. 1                                |
| \*.city                    | City                                                                                      | Main ave. 1                                |
| \*.country                 | Country (ISO 3166-1 alpha-3)                                                              | USA                                        |
| \*.login                   | Client login                                                                              | john\_doe                                  |
| \*.email                   | E-mail                                                                                    | <foo@bar.com>                              |
| \*.name                    | Full name                                                                                 | John Smith                                 |
| \*.phone                   | Phone number                                                                              | +1 456 890                                 |
| \*.state                   | State                                                                                     | CA                                         |
| \*.zip                     | Postal code                                                                               | 123456                                     |
| \*.login                   | Login                                                                                     | john\_doe                                  |
| custom\_fields             | Additional custom fields (<mark style="color:orange;">\*</mark>)                          | -                                          |
| options                    | Options (<mark style="color:orange;">\*</mark>)                                           | -                                          |
| \*.force3d                 | Forced 3-D Secure verification                                                            | 1                                          |
| \*.return\_url             | <mark style="color:orange;">URL</mark> to redirect customer when the payment is completed | <http://my.url>                            |
| \*.auto\_charge            | Executes Charge operation (is used for 1-stage payments)                                  | 1                                          |
| \*.terminal                | Terminal                                                                                  | TERM12                                     |
| \*.recurring               | Flag of the recurring payment                                                             | 1                                          |
| \*.secure3d20\_return\_url | Notification <mark style="color:orange;">URL</mark> 3-D Secure 2.0                        | <http://return.url>                        |
| \*.exemption\_mit          | Exemption MIT flag                                                                        | 1                                          |
| secure3d                   | 3-D Secure authentication (<mark style="color:orange;">\*</mark>)                         | -                                          |
| \*.xid                     | PaRes transaction identifier (XID)                                                        | <p>8Rg2xYbxLUGsfZlkoh1JxAQ</p><p>FBM=</p>  |
| \*.cavv                    | Cardholder authentication verification value from PaRes                                   | <p>AAABCBVRA2EYZXQBV1EDAAA</p><p>AAA=</p>  |
| \*.eci                     | E-commerce indicator (ECI)                                                                | 05                                         |
| \*.ds\_trans\_id           | Directory server transaction ID                                                           | <p>Rcm70YAaT/7SZnqVGFQkm/N</p><p>JnbQ=</p> |
| recurring\_details         | Recurrent payment details (<mark style="color:orange;">\*</mark>)                         | -                                          |
| \*.parent\_order\_id       | Parent order ID                                                                           | 74615664219665657                          |
| \*.trace\_id               | Trace ID                                                                                  | MCC8454300719                              |
| \*.indicator               | Recurrent payment indicator                                                               | m101                                       |
| {% endtab %}               |                                                                                           |                                            |

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id) and may contain extra fields described below.

| Name          | Description                                                                  | Example                                              |
| ------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------- |
| form3d\_html  | 3-D Secure form in HTML                                                      | \<form id="form3d" ...                               |
| form3d        | 3-D Secure form (<mark style="color:orange;">\*</mark>)                      | -                                                    |
| \*.MD         | MD parameter                                                                 | NTY3NDg0NjMzMjA0MDU1OQ==                             |
| \*.PaReq      | PaReq parameter                                                              | Y3NDg0NjMzM0MDU1OQ                                   |
| \*.TermUrl    | System <mark style="color:orange;">URL</mark> where transaction is finalized | [http://bizon.one/complete](http://box.com/complete) |
| \*.action     | Acquirer ACS <mark style="color:orange;">URL</mark>                          | <http://bank.com>                                    |
| \*.method     | Form method                                                                  | POST                                                 |
| {% endtab %}  |                                                                              |                                                      |
| {% endtabs %} |                                                                              |                                                      |

#### Examples

{% tabs %}
{% tab title="Example (only required fields provided)" %}

```graphql
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
<
```

```json
{
   "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"
      }
   ]
}
```

{% endtab %}

{% tab title="Example (all fields provided)" %}

```graphql
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"
},
"client" : {
"address" : "Main ave. 1",
"city" : "San Francisco",
"country" : "USA",
"email" : "foo@bar.com",
"name" : "John Smith",
"phone" : "+1 456 890",
"state" : "CA",
"zip" : "123456"
},
"description" : "Book sale #453",
"location" : {
"ip" : "6.6.6.6"
},
"merchant_order_id" : "5678",
"options" : {
"force3d" : 0,
"return_url" : "http://shop.com",
"terminal" : ""
},
"pan" : "4111111111111111",
"segment" : "987654321"
}' '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: 470
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 1018
<
```

```json
{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "0.00",
      "amount_refunded": "0.00",
      "auth_code": "AUTH12",
      "card": {
        "holder": "John Smith",
        "subtype": "classic",
        "type": "visa"
      },
      "client": {
        "address": "Main ave. 1",
        "city": "San Francisco",
        "country": "USA",
        "email": "foo@bar.com",
        "name": "John Smith",
        "phone": "+1 456 890",
        "state": "CA",
        "zip": "123456"
      },
      "created": "2016-08-22 15:39:49",
      "currency": "USD",
      "custom_fields": {},
      "description": "Book sale #453",
      "descriptor": "TESTMERCH/TERM",
      "id": "23014806815093624",
      "issuer": {
        "bin": "411111",
        "country": "UKR",
        "title": "TestBank"
      },
      "location": {
        "ip": "6.6.6.6"
      },
      "merchant_order_id": "5678",
      "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:49",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "authorize"
        }
      ],
      "pan": "411111****1111",
      "secure3d": {},
      "segment": "987654321",
      "status": "authorized",
      "updated": "2016-08-22 15:39:49"
    }
  ]
}
```

{% endtab %}

{% tab title="Example (3-D Secure)" %}

```graphql
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"
},
"options" : {
"force3d" : 1
},
"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: 180
>
< HTTP/1.1 201 Created
< Content-Type: application/json
< Content-Length: 1083
<
{
"orders" : [
{
"amount" : "9.99",
"amount_charged" : "0.00",
"amount_refunded" : "0.00",
"card" : {
"holder" : "John Smith",
"subtype" : "classic",
"type" : "visa"
},
"client" : {},
"created" : "2016-08-22 15:39:46",
"currency" : "USD",
"custom_fields" : {},
"description" : null,
"form3d" : {
"MD" : "MjMwMTQ4MDYwNzgwNjEzMDM=",
"PaReq" : "PaReq",
"TermUrl" : "http://localhost:5002/complete/secure3d",
"action" : "http://localhost:5002/test/bank",
"method" : "GET"
},
"form3d_html" : "<form id=\"form3d\" method=\"GET\" action=\"http://localhost:5002/test/bank\"><input type=\"hidden\"
name=\"MD\" value=\"MjMwMTQ4MDYwNzgwNjEzMDM=\"><input type=\"hidden\" name=\"PaReq\" value=\"PaReq\"><input type=\"hidden\"
name=\"TermUrl\" value=\"http://localhost:5002/complete/secure3d\"></form><script>window.onload = function()
{document.forms['form3d'].submit();}</script>",
"id" : "23014806078061303",
"issuer" : {
"bin" : "411111",
"country" : "UKR",
"title" : "TestBank"
},
"location" : {
"ip" : "6.6.6.6"
},
"merchant_order_id" : null,
"operations" : [],
"pan" : "411111****1111",
"secure3d" : {
"reason" : "force3d",
"scenario" : "unknown"
},
"status" : "prepared",
"updated" : "2016-08-22 15:39:46"
}
]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.&#x20;

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.
{% endhint %}

### <mark style="color:blue;">Reverse (PUT /orders/:id/reverse)</mark>

{% tabs %}
{% tab title="Parameters" %}
Not supported.
{% endtab %}

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id).
{% endtab %}

{% tab title="Example" %}

```graphql
curl -v -X PUT -H 'Content-Type: application/json' 'http://project:***@api.box:5001/orders/23014805692462630/reverse'
> PUT /orders/23014805692462630/reverse HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
>
< Content-Type: application/json
< Content-Length: 1115
<
```

```json
{
  "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:44",
      "currency": "USD",
      "custom_fields": {},
      "description": null,
      "descriptor": "TESTMERCH/TERM",
      "id": "23014805692462630",
      "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:45",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "authorize"
        },
        {
          "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:50",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "reverse"
        }
      ],
      "pan": "411111****1111",
      "secure3d": {},
      "status": "reversed",
      "updated": "2016-08-22 15:39:50"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">Charge (PUT /orders/:id/charge)</mark>

{% tabs %}
{% tab title="Parameters" %}

| Name         | Description      | Example |
| ------------ | ---------------- | ------- |
| amount       | Amount of charge | 9.99    |
| {% endtab %} |                  |         |

{% tab title="Responce" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id).
{% endtab %}

{% tab title="Example (full charge)" %}

```graphql
curl -v -X PUT -H 'Content-Type: application/json' 'http://project:***@api.box:5001/orders/23014806643308174/charge'
> PUT /orders/23014806643308174/charge HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 1113
<
```

```json
{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "9.99",
      "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"
        },
        {
          "amount": "9.99",
          "auth_code": "AUTH12",
          "cashflow": {
            "amount": "9.99",
            "currency": "USD",
            "fee": "0.30",
            "incoming": "9.69",
            "receivable": "9.69",
            "reserve": "0.00"
          },
          "created": "2016-08-22 15:39:53",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "charge"
        }
      ],
      "pan": "411111****1111",
      "secure3d": {},
      "status": "charged",
      "updated": "2016-08-22 15:39:53"
    }
  ]
}
```

{% endtab %}

{% tab title="Example (partial charge)" %}

```graphql
curl -v -X PUT -H 'Content-Type: application/json' -d '{
"amount" : 1.99
}' 'http://project:***@api.box:5001/orders/23014806312026412/charge'
> PUT /orders/23014806312026412/charge HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
> Content-Length: 15
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 1113
<
```

```json
{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "1.99",
      "amount_refunded": "0.00",
      "auth_code": "AUTH12",
      "card": {
        "holder": "John Smith",
        "subtype": "classic",
        "type": "visa"
      },
      "client": {},
      "created": "2016-08-22 15:39:47",
      "currency": "USD",
      "custom_fields": {},
      "description": null,
      "descriptor": "TESTMERCH/TERM",
      "id": "23014806312026412",
      "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:47",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "authorize"
        },
        {
          "amount": "1.99",
          "auth_code": "AUTH12",
          "cashflow": {
            "amount": "1.99",
            "currency": "USD",
            "fee": "0.06",
            "incoming": "1.93",
            "receivable": "1.93",
            "reserve": "0.00"
          },
          "created": "2016-08-22 15:39:51",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "charge"
        }
      ],
      "pan": "411111****1111",
      "secure3d": {},
      "status": "charged",
      "updated": "2016-08-22 15:39:51"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">Refund (PUT /orders/:id/refund)</mark>

{% tabs %}
{% tab title="Parameters" %}

| Name         | Description      | Example |
| ------------ | ---------------- | ------- |
| amount       | Amount of refund | 9.99    |
|              |                  |         |
|              |                  |         |
| {% endtab %} |                  |         |

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id).
{% endtab %}

{% tab title="Example (full refund)" %}

```graphql
curl -v -X PUT -H 'Content-Type: application/json' 'http://project:***@api.box:5001/orders/23014806643308174/refund'
> PUT /orders/23014806643308174/refund HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
>
< Content-Type: application/json
< Content-Length: 1404
<
```

```json
{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "9.99",
      "amount_refunded": "9.99",
      "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"
        },
        {
          "amount": "9.99",
          "auth_code": "AUTH12",
          "cashflow": {
            "amount": "9.99",
            "currency": "USD",
            "fee": "0.30",
            "incoming": "9.69",
            "receivable": "9.69",
            "reserve": "0.00"
          },
          "created": "2016-08-22 15:39:53",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "charge"
        },
        {
          "amount": "9.99",
          "auth_code": "AUTH12",
          "cashflow": {
            "amount": "-9.99",
            "currency": "USD",
            "fee": "0.00",
            "incoming": "-9.99",
            "receivable": "-9.99",
            "reserve": "0.00"
          },
          "created": "2016-08-22 15:39:55",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "refund"
        }
      ],
      "pan": "411111****1111",
      "secure3d": {},
      "status": "refunded",
      "updated": "2016-08-22 15:39:55"
    }
  ]
}
```

{% endtab %}

{% tab title="Example (partial refund)" %}

```graphql
curl -v -X PUT -H 'Content-Type: application/json' -d '{
"amount" : 1.99
}' 'http://project:***@api.box:5001/orders/23014806312026412/refund'
> PUT /orders/23014806312026412/refund HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
> Content-Length: 15
>
< Content-Type: application/json
< Content-Length: 1404
<
```

```json
{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "1.99",
      "amount_refunded": "1.99",
      "auth_code": "AUTH12",
      "card": {
        "holder": "John Smith",
        "subtype": "classic",
        "type": "visa"
      },
      "client": {},
      "created": "2016-08-22 15:39:47",
      "currency": "USD",
      "custom_fields": {},
      "description": null,
      "descriptor": "TESTMERCH/TERM",
      "id": "23014806312026412",
      "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:47",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "authorize"
        },
        {
          "amount": "1.99",
          "auth_code": "AUTH12",
          "cashflow": {
            "amount": "1.99",
            "currency": "USD",
            "fee": "0.06",
            "incoming": "1.93",
            "receivable": "1.93",
            "reserve": "0.00"
          },
          "created": "2016-08-22 15:39:51",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "charge"
        },
        {
          "amount": "1.99",
          "auth_code": "AUTH12",
          "cashflow": {
            "amount": "-1.99",
            "currency": "USD",
            "fee": "0.00",
            "incoming": "-1.99",
            "receivable": "-1.99",
            "reserve": "0.00"
          },
          "created": "2016-08-22 15:39:52",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "refund"
        }
      ],
      "pan": "411111****1111",
      "secure3d": {},
      "status": "refunded",
      "updated": "2016-08-22 15:39:52"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">Cancel (PUT /orders/:id/cancel)</mark>

{% hint style="info" %}
This is the equivalent of making [Reverse](#reverse-put-orders-id-reverse) or [Refund](#refund-put-orders-id-refund) depending on current order state.
{% endhint %}

{% tabs %}
{% tab title="Parameters" %}

| Name         | Description                                     | Example |
| ------------ | ----------------------------------------------- | ------- |
| amount       | Amount of refund (not applicable for reversing) | 9.99    |
| {% endtab %} |                                                 |         |

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id).
{% endtab %}

{% tab title="Example" %}

```graphql
curl -v -X PUT -H 'Content-Type: application/json' 'http://project:***@api.box:5001/orders/23014808614292147/cancel'
> PUT /orders/23014808614292147/cancel HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 1404
<
```

```json
{
  "orders": [
    {
      "amount": "9.99",
      "amount_charged": "9.99",
      "amount_refunded": "9.99",
      "auth_code": "AUTH12",
      "card": {
        "holder": "John Smith",
        "subtype": "classic",
        "type": "visa"
      },
      "client": {},
      "created": "2016-08-22 15:39:56",
      "currency": "USD",
      "custom_fields": {},
      "description": null,
      "descriptor": "TESTMERCH/TERM",
      "id": "23014808614292147",
      "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:56",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "authorize"
        },
        {
          "amount": "9.99",
          "auth_code": "AUTH12",
          "cashflow": {
            "amount": "9.99",
            "currency": "USD",
            "fee": "0.30",
            "incoming": "9.69",
            "receivable": "9.69",
            "reserve": "0.00"
          },
          "created": "2016-08-22 15:39:56",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "charge"
        },
        {
          "amount": "9.99",
          "auth_code": "AUTH12",
          "cashflow": {
            "amount": "-9.99",
            "currency": "USD",
            "fee": "0.00",
            "incoming": "-9.99",
            "receivable": "-9.99",
            "reserve": "0.00"
          },
          "created": "2016-08-22 15:39:57",
          "currency": "USD",
          "iso_message": "Approved",
          "iso_response_code": "00",
          "status": "success",
          "type": "refund"
        }
      ],
      "pan": "411111****1111",
      "secure3d": {},
      "status": "refunded",
      "updated": "2016-08-22 15:39:57"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">Repeating payment (POST /orders/:id/rebill)</mark>

{% tabs %}
{% tab title="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 (<mark style="color:orange;">\*</mark>) | -       |
| \*.ip        | IP-address                                                      | 8.8.8.8 |
| {% endtab %} |                                                                 |         |

{% tab title="Optional parameters" %}

| Name               | Description                                                       | Example       |
| ------------------ | ----------------------------------------------------------------- | ------------- |
| options            | Options (<mark style="color:orange;">\*</mark>)                   | -             |
| \*.recurring       | Flag of the recurring payment                                     | 1             |
| recurring\_details | Recurrent payment details (<mark style="color:orange;">\*</mark>) | -             |
| \*.trace\_id       | Trace ID                                                          | MCC8454300719 |
| \*.indicator       | Recurrent payment indicator                                       | m101          |
| {% endtab %}       |                                                                   |               |

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id).
{% endtab %}

{% tab title="Example" %}

```graphql
curl -v -X POST -H 'Content-Type: application/json' -d '{
"amount" : 9.99,
"cvv" : "123"
}' 'http://project:***@api.box:5001/orders/23014808614292147/rebill'
> POST /orders/23014808614292147/rebill HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
> Content-Length: 27
>
< Content-Type: application/json
< Content-Length: 815
<
```

```json
{
  "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:58",
      "currency": "USD",
      "custom_fields": {},
      "description": null,
      "descriptor": "TESTMERCH/TERM",
      "id": "23014809139351770",
      "issuer": {
        "bin": "411111",
        "country": "UKR",
        "title": "TestBank"
      },
      "location": {},
      "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:58",
          "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:58"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">Original credit transaction (OCT) (POST /orders/:id/credit)</mark>

{% tabs %}
{% tab title="Required parameters" %}

| Name         | Description | Example |
| ------------ | ----------- | ------- |
| amount       | Amount      | 9.99    |
| {% endtab %} |             |         |

{% tab title="Optional parameters" %}
Optional parameters are the same as for [Authorize](#authorize-post-orders-authorize) operation.
{% endtab %}

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id)
{% endtab %}

{% tab title="Example" %}

```graphql
curl -v -X POST -H 'Content-Type: application/json' -d '{
"amount" : 9.99,
"currency" : "USD"
"location" : {
"ip" : "8.8.8.8"
}
}' 'http://project:***@api.box:5001/orders/23014808614292147/credit'
> POST /orders/23014808614292147/credit HTTP/1.1
> Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
> Host: api.box:5001
> Content-Type: application/json
> Content-Length: 27
>
< Content-Type: application/json
< Content-Length: 815
<
{
"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:58",
"currency" : "USD",
"custom_fields" : {},
"description" : null,
"descriptor" : "TESTMERCH/TERM",
"id" : "23014809139351770",
"issuer" : {
"bin" : "411111",
"country" : "UKR",
"title" : "TestBank"
},
"location" : {},
"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:58",
"currency" : "USD",
"iso_message" : "Approved",
"iso_response_code" : "00",
"status" : "success",
"type" : "credit"
}
],
"pan" : "411111****1111",
"secure3d" : {},
"status" : "credited",
"updated" : "2016-08-22 15:39:58"
}
]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">Original credit transaction without link to order (OCT) (POST /orders/credit)</mark>

{% tabs %}
{% tab title="Required parameters" %}

| Name         | Description       | Example          |
| ------------ | ----------------- | ---------------- |
| amount       | Amount            | 9.99             |
| pan          | Card number (PAN) | 4111111111111111 |
| {% endtab %} |                   |                  |

{% tab title="Optional parameters" %}
Optional parameters are the same as for [Authorize](#authorize-post-orders-authorize) operation.
{% endtab %}

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id).
{% endtab %}

{% tab title="Example" %}

```graphql
curl -X POST -H 'Authorization: Basic cHJvamVjdDpwYXNzd29yZA==' -i 'http://project:***@api.box:5001/orders/credit' --data '
{
"amount" : "99.99",
"pan" : "4111111111111111"
}'
> HTTP/1.1 200 OK
> Server: nginx/1.10.3 (Ubuntu)
> Date: Tue,
> 18 May 2021 10: 37: 12 GMT
> Content-Type: application/json
> Content-Length: 786
> Connection: keep-alive
>
{
"orders": [
{
"descriptor": " merchant123",
"amount": "99.99",
"status": "credited",
"client": {},
"amount_refunded": "0.00",
"description": null,
"operations": [
{
"auth_code": "301541",
"cashflow": {
"currency": "USD",
"fee": "0.00",
"incoming": "-99.99",
"reserve": "3.00",
"receivable": "-102.99",
"amount": "-99.99"
},
"status": "success",
"amount": "99.99","iso_response_code": "00",
"currency": "USD",
"created": "2021-05-18 13:37:12",
"type": "credit",
"iso_message": "Approved"
}
],
"pan": "411111****1111",
"secure3d": {},
"created": "2021-05-18 13:37:11",
"custom_fields": {},
"currency": "USD",
"card": {
"type": "mastercard",
"subtype": "standard",
"expiration": "0/0"
},
"id": "61277755379729234",
"issuer": {
"bin": "527644"
},
"amount_charged": "0.00",
"location": {},
"auth_code": "301541",
"merchant_order_id": null,
"updated": "2021-05-18 13:37:12"
}
]
}
```

{% endtab %}
{% endtabs %}

### <mark style="color:blue;">Authorization with the transfer of an encrypted token ( POST /orders/token\_pay)</mark>

{% tabs %}
{% tab title="Required parameters" %}

|              |                                                                 |                                                                            |
| ------------ | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
| amount       | Amount                                                          | 9.99                                                                       |
| dsrp         | DSRP data (<mark style="color:orange;">\*</mark>)               | -                                                                          |
| \*.type      | Token type                                                      | apple\_pay                                                                 |
| \*.token     | DSRP token                                                      | <p>eyJwYXltZW50RGF0YS...kljcEJhOTR</p><p>WTi9KVGdhOFc3NUlXQUE9PSJ9fQ==</p> |
| location     | Client location details (<mark style="color:orange;">\*</mark>) | -                                                                          |
| \*.ip        | IP-address                                                      | 8.8.8.8                                                                    |
| {% endtab %} |                                                                 |                                                                            |

{% tab title="Example" %}

```graphql
curl -X POST -H 'Authorization: Basic cHJvamVjdDpwYXNzd29yZA==' -i 'http://project:***@api.box:5001/orders/token_pay' --data '{
"dsrp": {
"type": "apple_pay",
"token":
"eyJwYXltZW50RGF0YSI6eyJoZWFkZXIiOnsicHVibGljS2V5SGFzaCI6IjBjV0haajNQeTIwTnhoOFZyQU5mY1hTRkZhYU5DSk05SHBDUGlVaGI2M0dXaTcrQXlhMEJtc0tmRUxvSy9QcCsxaHZtSnpPMER0a2RZcnRMUVJuS1JLVU1YK0tmRXNRTzNlS0xFT2FSbTEycWYxamdYRzdIVUUxcitCbHJLOUJDMjRRenlaa3FZVmJkVFNiRThDVG},
"amount": "100",
"currency" : "USD",
"description": "Pay for cinema",
"payment_type": "card",
"client": {
"phone": "+18961234545",
"zip": 152589,
"name": "Fox",
"city": "City",
"email": "max@test.com",
"country": "USA",
"address": "Some address",
"login": "foo"
},
"location": {
"ip": "6.6.6.6"
}
}
'
{
"orders": [
{
"pan": "410937****4320",
"card": {
"subtype": "classic",
"type": "visa",
"expiration": "7/20"},
"operations": [
{
"currency": "USD",
"created": "2022-06-03 11:24:42",
"auth_code": "AUTH12",
"status": "success",
"amount": "100.00",
"iso_message": "Approved",
"type": "authorize",
"cashflow": {
"receivable": "-3.00",
"reserve": "3.00",
"amount": "0.00",
"fee": "0.00",
"currency": "USD",
"incoming": "0.00"
},
"id": "1",
"iso_response_code": "00"
}
],
"created": "2022-06-03 11:24:41",
"currency": "USD",
"amount": "100.00",
"descriptor": "1/1",
"updated": "2022-06-03 11:24:42",
"amount_charged": "0.00",
"custom_fields": {},
"merchant_order_id": null,
"id": "69702830548094412",
"secure3d": {
"dsrp_type": "apple_pay",
"reason": "dsrp",
"authorization_status": "Y",
"dsrp": "1",
"eci": "5",
"xid": "2686f5297f123ec7fd9d31074d43d201953ca75f098890375f13aed2737d92f2",
"cavv": "Af9x/QwAA/DjmU65oyc1MAABAAA=",
"version": "1",
"scenario": "unknown"
},
"description": "Pay for cinema",
"auth_code": "AUTH12",
"location": {
"ip": "6.6.6.6"
},
"status": "authorized",
"amount_refunded": "0.00",
"rrn": "69702830725209556",
"issuer": {
"bin": "410937"
},
"client": {
"address": "Some address",
"login": "foo",
"name": "Fox",
"city": "City",
"zip": "152589",
"country": "USA",
"email": "max@test.com",
"phone": "+18961234545"
}
}
]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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](#authorize-post-orders-authorize), except fields pan, card.\*, secure3d.\*, options.force3d, options.return\_url, options.secure3d20\_return\_url.
{% endhint %}

### <mark style="color:blue;">Completion of 3-D Secure Authentication (POST /orders/:id/complete)</mark>

{% tabs %}
{% tab title="Required parameters" %}

| Name         | Description                   | Example               |
| ------------ | ----------------------------- | --------------------- |
| PaRes        | Payer authentication response | 424EF64895CAE9797497F |
| {% endtab %} |                               |                       |

{% tab title="Example" %}

```graphql
curl -X POST 'http://project:***@api.box:5001/orders/43809080318125930/complete' -H 'accept: application/json' -H 'authorization: Basic
bWVyY2hhbnRfdGVzdDpQQVFpemtWeCtDUlJVbTEr' -H 'Content-Type: application/json' -d '{"PaRes": "YAED53A345D"}'
{
"orders": [
{
"description": "Book sale 453",
"auth_code": "AUTH12",
"amount": "100.99","merchant_order_id": null,
"id": "43809080318125930",
"updated": "2019-03-20 18:47:03",
"pan": "411111****1111",
"currency": "USD",
"descriptor": "321/123",
"amount_charged": "100.99",
"created": "2019-03-20 18:46:15",
"status": "charged",
"amount_refunded": "0.00"
}
]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The endpoint sends a response to the authorization request. When resubmitting the request to the endpoint the answer will be received: "Order already

completed".
{% endhint %}

### <mark style="color:blue;">Completion of 3-D Secure 2.0 Authentication (POST /orders/:id/complete3d20)</mark>

{% tabs %}
{% tab title="Optional parameters" %}

| Name         | Description                                                                            | Example                                      |
| ------------ | -------------------------------------------------------------------------------------- | -------------------------------------------- |
| cres         | <p>Base64 encoded string containing the results of 3-D</p><p>Secure authentication</p> | ewogICJhY3NUcmFuc0...W9uIiA6ICIyLjEuMCIKfQ== |
| {% endtab %} |                                                                                        |                                              |

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id).
{% endtab %}

{% tab title="Example" %}

```graphql
curl -X POST -H 'Authorization: Basic cHJvamVjdDpwYXNzd29yZDEyMw==' -i
'http://project:***@api.box:5001/orders/57937457169525773/complete3d20'
{
"orders": [{
"merchant_order_id": null,
"client": {},
"secure3d": {
"reason": "force3d",
"xid": "635fb7bc-7acc-451e-a37d-606f1febae78",
"eci": "5",
"version": "2",
"authorization_status": "Y",
"dsrp": "0",
"cavv": "AAABBZEEBgAAAAAAAAQGAAAAAAA=",
"scenario": "full"
},
"updated": "2020-12-18 13:13:43",
"amount": "123.00",
"currency": "USD",
"status": "authorized",
"pan": "510033****0101",
"amount_refunded": "0.00",
"amount_charged": "0.00",
"operations": [{
"amount": "123.00",
"auth_code": "123",
"cashflow": {
"currency": "USD",
"receivable": "-3.69",
"amount": "0.00",
"fee": "0.00",
"incoming": "0.00",
"reserve": "3.69"
},
"type": "authorize",
"iso_message": "Approved",
"created": "2020-12-18 13:13:43",
"iso_response_code": "00",
"status": "success",
"currency": "USD"
}],
"auth_code": "123",
"description": null,
"custom_fields": {},
"location": {
"ip": "6.6.6.6"
},
"card": {
"type": "mastercard",
"expiration": "10/22",
"subtype": "standard"},
"issuer": {
"bin": "510033"
},
"id": "57937457169525773",
"created": "2020-12-18 13:09:52"
}]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

### <mark style="color:blue;">Continue 3DS Method URL of authentication (POST /orders/:id/resume)</mark>

{% tabs %}
{% tab title="Parameters" %}
Not supported
{% endtab %}

{% tab title="Response" %}
Fields in response are the same as described in [Order information](#order-information-get-orders-id)
{% endtab %}

{% tab title="Example" %}

```graphql
curl -X POST -H 'Authorization: Basic cHJvamVjdDpwYXNzd29yZDEyMw==' -i 'http://project:***@api.box:5001/orders/60391976929806541/resume'
{
"orders": [{
"amount": "1.00",
"custom_fields": {},
"id": "60391976929806541",
"form3d": {
"threeDSSessionData": "NjAzOTE5NzY5Mjk4MDY1NDE=",
"method": "POST",
"action": "http://checkout.***.local:80/complete/secure3d20"
},
"issuer": {
"bin": "220138"
},
"amount_refunded": "0.00",
"amount_charged": "0.00",
"created": "2021-04-08 12:29:19",
"form3d_html": "<form id=\"form3d\" method=\"POST\" action=\"http://checkout.***.local:80/complete/secure3d20\"><input
type=\"hidden\" name=\"threeDSSessionData\" value=\"NjAzOTE5NzY5Mjk4MDY1NDE=\"></form><script>window.onload = function()
{document.forms['form3d'].submit();}</script>",
"updated": "2021-04-08 12:29:20",
"status": "prepared",
"description": null,
"location": {
"ip": "6.6.6.6"
},
"currency": "EUR",
"client": {},
"pan": "220138****0013",
"merchant_order_id": null,
"operations": [],
"card": {
"holder": "John Smith",
"type": "mir",
"subtype": "unknown",
"expiration": "12/21"
},
"secure3d": {
"dsrp": "0",
"scenario": "unknown",
"reason": "force3d",
"eci": "0",
"version": "2"
}
}]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The endpoint continues the authorization described in [Payments with 3-D Secure 2.0](#continue-3ds-method-url-of-authentication-post-orders-id-resume). Maximum time waiting for a response to a request - 10 seconds
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bizon.one/08.01/api-payment-gateway/actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.