🏁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

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

{
    "error": "Invalid API key"
}

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

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

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

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

HTTP/1.1 204 No Content

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

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

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

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

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

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

PreviousPayment Links NextInvoices

Last updated 2 years ago