# API overview

## <mark style="color:blue;">General information</mark>

* Requests are made through HTTP 1.1 using SSL and *Basic-Authentication*.&#x20;
* Requests and responses are encoded in *UTF-8*.
* Requests and responses are *JSON* structures.
* When getting information use the method *GET*, when manipulation with data methods *POST* or *PUT* is required.&#x20;
* In *GET*-requests parameters are passed as *QUERY STRING*.
* In *POST*-requests parameters are passed as a body of the *POST*-request, in some cases *QUERY STRING* could be used too.
* Success responses are sent with a*HTTP*-status 200 or 201. In case of an error, the status may vary (see Response codes).

## <mark style="color:blue;">(1) Authentication</mark>

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

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

## <mark style="color:blue;">(2) Response codes</mark>

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

<table><thead><tr><th width="93">Code</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td><p>This code means the operation you requested has been processed successfully. Depending on which operation you have requested, it may</p><p>tell that authorization, reversal, charge or refund has been made</p></td></tr><tr><td>201</td><td>An order has been created and it is waiting for additional input</td></tr><tr><td>402</td><td>The operation has been declined by the acquirer or rejected by the gateway</td></tr><tr><td>422</td><td>Request validation failed</td></tr><tr><td>500</td><td>Error on the acquirer or gateway side</td></tr></tbody></table>

## (3) Failure type

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

<table><thead><tr><th width="131">Code</th><th>Description</th></tr></thead><tbody><tr><td>declined</td><td>The acquirer has declined the transaction</td></tr><tr><td>fraud</td><td>The transaction has been declined by fraud prevention rules on the gateway side</td></tr><tr><td>rejected</td><td>The transaction has been declined by the gateway</td></tr><tr><td>error</td><td>Failure due to an error on the acquirer or gateway side</td></tr><tr><td>validation</td><td>The request was not processed because of incorrect input</td></tr></tbody></table>

## (4) Working flow

## Verifying successful operation

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

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

## (4.1.) Error handling

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

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

Description of an error is located in a failure\_message field. If there is an order created during a request, its identifier is returned in an order\_id field.

## (4.2.) Processing declined transactions

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

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

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

In the order information for Soft-Decline, iso\_response\_code will be A1.

## (4.3.) Validation

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

Example:

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

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

{ "errors" : \[ { "attribute" : "required", "details" : \[ "(true)" ], "message" : "Required", "uri" : "#/amount" }, { "message" : "Unknown property", "uri" : "#/foo" } ], "failure\_message" : "Validation failed", "failure\_type" : "validation", "order\_id" : null }

## (4.4.) Sample code

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

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

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

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

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

{ "errors" : \[ { "attribute" : "required", "details" : \[ "(true)" ], "message" : "Required", "uri" : "#/amount" }, { "message" : "Unknown property", "uri" : "#/foo" } ], "failure\_message" : "Validation failed", "failure\_type" : "validation", "order\_id" : null }


---

# 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.up2.money/08.01/api-payment-gateway/api-overview.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.