# Checkout

## Introduction

Checkout is a feature provided by Sonic Payment Gateway that allows merchants to easily accept payments from customers. This guide will walk through the process of creating, retrieving, updating and deleting checkouts, as well as getting all checkouts.

## Create a Checkout

To create a checkout, you will need to make a POST request to the checkout endpoint and provide the necessary information about the checkout in the request body. Here's an example of creating a checkout using cURL:

<mark style="color:green;">`POST`</mark> `https://api.sonicpay.org/checkouts`

#### Request Body

| Name                                            | Type                          | Description |
| ----------------------------------------------- | ----------------------------- | ----------- |
| amount<mark style="color:red;">\*</mark>        | 100                           |             |
| currency<mark style="color:red;">\*</mark>      | USDT                          |             |
| description<mark style="color:red;">\*</mark>   | Test                          |             |
| redirect\_url<mark style="color:red;">\*</mark> | <https://example.com/success> |             |
| cancel\_url<mark style="color:red;">\*</mark>   | <https://example.com/cancel>  |             |

{% tabs %}
{% tab title="201: Created " %}

```javascript
  {
    "id": "ch_1GtL5K2eZvKYlo2CYzkj3eZg",
    "amount": 100,
    "currency": "USDT",
    "description": "Test checkout",
    "redirect_url": "https://example.com/success"
    "cancel_url": "https://example.com/cancel"
    "status": "created",
    "metadata": {},
    "created_at": "2022-01-01T12:00:00Z"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
    "error": "Invalid API key"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
    "error": {
        "amount": [
            "The amount must be at least 1."
        ],
        "currency": [
            "The selected currency is invalid."
        ],
        "description": [
            "The description field is required."
        ]
    }
}

```

{% endtab %}
{% endtabs %}

Example cURL:&#x20;

```
curl --location --request POST 'https://api.sonicpay.org/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "amount": 100,
    "currency": "USDT",
    "description": "Test checkout",
    "redirect_url": "https://example.com/success"
    "cancel_url": "https://example.com/cancel"
}'
```

The following table lists the parameters that can be included in the request body when creating a checkout:

| Parameter     | Type    | Description                                                                                  |
| ------------- | ------- | -------------------------------------------------------------------------------------------- |
| amount        | integer | The total amount of the checkout in the smallest unit of the currency (e.g. cents for USDT). |
| currency      | string  | The currency of the checkout. Must be a valid ISO 4217 currency code.                        |
| description   | string  | A description of the checkout.                                                               |
| redirect\_url | string  | The URL that the customer will be redirected to after a successful payment.                  |
| cancel\_url   | string  | The URL that the customer will be redirected to after there is a failed payment.             |

If the request is successful, the response will contain the checkout object, including the checkout ID, which will be used for future interactions with the checkout.

## Get a Checkout&#x20;

To retrieve a specific checkout, you will need to make a GET request to the checkout endpoint and provide the checkout ID in the URL.&#x20;

<mark style="color:blue;">`GET`</mark> `https://api.sonicpay.org/checkouts/{checkout_id}`

#### Request Body

| Name                                           | Type  | Description |
| ---------------------------------------------- | ----- | ----------- |
| checkout\_id<mark style="color:red;">\*</mark> | 23732 |             |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{{
"id": "ch_1234567890",
"amount": 100,
"currency": "USDT",
"status": "created",
"description": "Test checkout",
"redirect_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"metadata": {},
"created_at": "2022-01-01T12:00:00Z"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
"error" : "Unauthorized",
"message" : "Invalid API Key"
}
```

{% endtab %}
{% endtabs %}

Here is the information that might be returned in a GET request to the endpoint `https://api.sonicpay.org/checkouts/{checkout_id}` when authorized:

| Property      | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| id            | string | The unique identifier for the checkout                                                 |
| amount        | number | The amount of the checkout in the currency specified                                   |
| currency      | string | The currency of the checkout                                                           |
| description   | string | The description of the checkout as provided in the initial request                     |
| redirect\_url | string | The URL that the user will be redirected to upon successful completion of the checkout |
| cancel\_url   | string | The URL that the user will be redirected to if they cancel the checkout                |
| status        | string | The current status of the checkout, such as `pending`, `successful`, or `failed`       |
| metadata      | object | Additional information associated with the checkout, in key-value pairs                |
| created\_at   | string | The date and time the checkout was created, in ISO 8601 format                         |

Here's an example of retrieving a checkout using cURL:

```javascript
curl --location --request GET 'https://api.sonicpay.org/checkouts/{checkout_id}' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

If the request is successful, the response will contain the checkout object.

## Delete a Checkout

To delete a checkout, you will need to make a DELETE request to the checkout endpoint and provide the checkout ID in the URL.&#x20;

<mark style="color:red;">`DELETE`</mark> `https://api.sonicpay.org/checkouts/{checkout_id}`

#### Request Body

| Name         | Type  | Description |
| ------------ | ----- | ----------- |
| checkout\_id | 23732 |             |

{% tabs %}
{% tab title="204: No Content " %}

```javascript
HTTP/1.1 204 No Content
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
    "error": "Invalid API key"
}
```

{% endtab %}

{% tab title="404: Not Found " %}

```javascript
HTTP/1.1 404 Not Found
Content-Type: application/json
{
    "error": "Checkout not found"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "Missing required parameter: checkout_id"
}
```

{% endtab %}
{% endtabs %}

Here's an example of deleting a checkout using cURL:

```
curl --location --request DELETE 'https://api.sonicpay.o/checkouts/{checkout_id}' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

If the request is successful, the response will be empty.

## **Update a Checkout**&#x20;

To update a checkout, you will need to make a PUT request to the checkout endpoint and provide the checkout ID in the URL.&#x20;

<mark style="color:orange;">`PUT`</mark> `https://api.sonicpay.org/checkouts/{checkout_id}'`

#### Request Body

| Name                                          | Type            | Description |
| --------------------------------------------- | --------------- | ----------- |
| description<mark style="color:red;">\*</mark> | Update Checkout |             |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "id": "ck_1H5jk2l",
    "amount": 100,
    "currency": "USDT",
    "description": "Updated Test checkout",
    "status": "created",
    "redirect_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "created_at": "2022-09-22T10:00:00.000000Z"
}

```

{% endtab %}
{% endtabs %}

Here's an example of updating a checkout using cURL:

```
curl --location --request PUT 'https://api.sonicpay.org/checkouts/{checkout_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "description": "Updated Test checkout"
}'
```

Note that other parameters such as `amount` and `currency` cannot be updated using this endpoint.

## **Get all Checkouts**

make a GET request to the following endpoint:

* `status` - filter checkouts by status (ex. `status=completed`)
* `created_at` - filter checkouts by created\_at timestamp (ex. `created_at=2022-01-01`)
* `updated_at` - filter checkouts by updated\_at timestamp (ex. `updated_at=2022-01-01`)

<mark style="color:blue;">`GET`</mark> `https://api.sonicpay.org/api/v1/checkouts?status=completed`

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
"data": [
{
"id": "ch_1234567890abcdef",
"status": "completed",
"amount": 100,
"currency": "USD",
"description": "Test checkout",
"redirect_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"created_at": "2022-01-01T00:00:00Z"
},
{
"id": "ch_0987654321fedcba",
"status": "completed",
"amount": 50,
"currency": "USD",
"description": "Another test checkout",
"redirect_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"created_at": "2022-01-02T00:00:00Z"
}
],
"meta": {
"total_count": 2
}
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{{
"error": {
"code": "unauthorized",
"message": "Invalid API key"
}
}
```

{% endtab %}
{% endtabs %}

Curl Example:

```
curl -X GET https://api.sonicpay.org/api/v1/checkouts?status=completed
```

Response:&#x20;

```
{
    "checkouts": [
        {
            "id": "183f0a97-9de8-4cdc-b130-e8dd5f06caf4",
            "reference": "3H1WTK8k8PC78p6TWEbKptT",
            "amount": 100,
            "coin": "USDT",
            "status": "completed",
            "metadata": {},
            "created_at": "2022-05-30T20:22:54.674Z",
            "updated_at": "2022-05-30T20:22:54.674Z"
        },
        {
            "id": "cbc49dc9-ca73-4458-8f1d-9bd33e7b33dc",
            "reference": "XXXX",
            "amount": 5,
            "coin": "USDT",
            "status": "completed",
            "metadata": {},
            "created_at": "2022-09-05T16:35:22.986Z",
            "updated_at": "2022-09-05T16:35:22.986Z"
        }
    ],
    "meta": {
        "total_count": 2,
        "total_pages": 1
    }
}

```

Sonic Payment Gateway also allows you to update, delete and get all checkouts.

Update a checkout: You can update the status of a checkout by making a PUT request to the checkout's endpoint with the updated status as the payload

Delete a checkout: You can delete a checkout by making a DELETE request to the checkout's endpoint.

Get all checkouts: You can get all checkouts by making a GET request to the checkouts endpoint.
