🏁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:

POST https://api.sonicpay.org/checkouts

Request Body

Name	Type	Description
amount*	100
currency*	USDT
description*	Test
redirect_url*	https://example.com/success
cancel_url*	https://example.com/cancel

201: Created

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

401: Unauthorized

{
    "error": "Invalid API key"
}

401: Unauthorized

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

Example cURL:

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

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.

GET https://api.sonicpay.org/checkouts/{checkout_id}

Request Body

Name	Type	Description
checkout_id*	23732

200: OK

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

401: Unauthorized

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

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:

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.

DELETE https://api.sonicpay.org/checkouts/{checkout_id}

Request Body

Name	Type	Description
checkout_id	23732

204: No Content

HTTP/1.1 204 No Content

401: Unauthorized

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

404: Not Found

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

400: Bad Request

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

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

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

PUT https://api.sonicpay.org/checkouts/{checkout_id}'

Request Body

Name	Type	Description
description*	Update Checkout

200: OK

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

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)

GET https://api.sonicpay.org/api/v1/checkouts?status=completed

200: OK

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

401: Unauthorized

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

Curl Example:

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

Response:

{
    "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.