Optionally used in Gateway Integration

Overview

This API can be used to query the status of a payment. This is an alternative to the callback URLs that the Pay1st Gateway redirects to.

In order to use this API effectively, the original reference that was provided in the Create Payment Request should be used.

Pre Requisites

An access token needs to be generated in order to use this API (see Authentication - Generate Access Token)

API Description

HTTP Headers

Header	Description/Value
Content-Type	`application/vnd.carry1st.payments.payment+json`
AccessToken	This is the `Access Token`field returned from the Authentication - Generate Access Token response. This should be in the format `Bearer <AccessToken>`

Note: The Basic Auth credentials will need to be provided by the Pay1st representative before using this API.

URL Format

GET: api/pay1st/payments?reference=<reference>

List of Query Parameters

Name	Description/Value
reference	This is the reference that was returned in the Create Payment Request

Response

Example Successful Response

The response will typically echo the combined request and the response fields in the Create Payment Request API. The only field that would typically be updated is the status.

{
    "countryCode": "NG",
    "currencyCode": "NGN",
    "amount": 100,
    "reference": "C-142710055596150-P",
    "partnerReference": "0e9c0b41-3ddf-4b2a-9e18-804a01a1508c",
    "partnerSettings": {
        "partnerId": 9,
        "webhookUrl": "https://webhook.success",
        "successCallbackUrl": "https://callback.success",
        "failureCallbackUrl": "https://callback.failure",
        "pendingCallbackUrl": "https://callback.pending",
        "cancelCallbackUrl": "https://callback.cancel"
    },
    "products": [
        {
            "title": "10Credits",
            "sku": "12345",
            "price": 100,
            "currencyCode": "NGN",
            "quantity": 1
        }
    ],
    "metadata": [
        {
            "key": "customerId",
            "value": "1"
        }
    ],
    "status": "NEW"
}

List of Statuses

Status	Description
NEW	The Payment has been created, but payment has not yet been processed
PENDING	Payment is processing
SUCCESSFUL	Payment has been completed successfully
FAILED	Payment has failed
CANCELLED	Payment has been cancelled by the customer
ABANDONED	Payment was not completed, and session has expired

HTTP Response Codes

The payment method API may return the following HTTP Response Codes:

HTTP Status Code	Name	Description
200	Success	This indicates that the request has been successful.
400	Bad Request	The Payment Reference may be incorrect
401	Unauthorized	The incorrect role value was used The incorrect `API Key` and `API Secret` combination was used (see Configuring API Credentials )
403	Forbidden	The incorrect `API Key` and `API Secret` do not have the appropriate permissions to make the request
429	Too Many Requests	The Partner is sending too many requests to this endpoint and will be rate limited

Error Handling

See Handling Error Codes for more details on handling error responses.