Used in Gateway Integration

Overview

A Payment Request needs to be created with the Pay1st gateway before an actual payment can be made. This API is a POST request that takes payment details as input, and returns payment identification information as a JSON response.

Pre Requisites

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

Request Signature

A valid signature should be generated for this request. See Gateway - Generating Signatures for a detailed description on how this should be implemented.

API Description

HTTP Headers

Header Name	Description
AccessToken	This is the `Access Token` field returned from the Authentication - Generate Access Token response. This should be in the format `Bearer <AccessToken>`
Content-Type	`application/vnd.carry1st.payments.payment+json`
X-SIGNATURE	This is the header that will contain the signature of the request. Refer to the Request Signing section above
X-TIMESTAMP	This is the current time in ISO-8601 format. This should be the same timestamp as the one used to generate the Signature

URL Format

https://<payments_url>/api/pay1st/payments/create

List of Create Payment POST fields

These are the list of POST parameters that needs to be passed from the Pay1st Partner to the Pay1st Gateway.

Param	Format	Mandatory	Description
amount	Decimal	Y	The amount to pay
countryCode	String	Y	The ISO-2 country code, e.g. ZA
currencyCode	String	Y	The currency code for the amount
partnerReference	String	Y	The Pay1st Partner reference that needs to be used for reconciliation. This value will be sent back via the Summary Webhook API Call. This must be unique for the lifetime of the integration
callbackSuccessUrl	String		If provided, this is the URL that will be used to redirect the customer when a payment is successful. If not present, the default value in Configuring Webhooks and Callbacks will be used
callbackFailureUrl	String		If provided, this is the URL that will be used to redirect the customer when a payment has failed. If not present, the default value in Configuring Webhooks and Callbacks will be used
callbackPendingUrl	String		If provided, this is the URL that will be used to redirect the customer when a payment is still pending completion. If not present, the default value in Configuring Webhooks and Callbacks will be used
callbackCancelUrl	String		If provided, this is the URL that will be used to redirect the customer when a payment is has been cancelled. If not present, the default value in Configuring Webhooks and Callbacks will be used
products	List of Product Fields	Y	The list of Product objects that identifies what the customer is paying for
metadata	List of Metadata Fields	Y	This is a list of key value pairs that can be used by the Partner to add any metadata relevant to the Payment
webhookUrl	String		If provided, this is the URL that will be used to notify the partner backend server of payment updated. If not present, the default value in Configuring Webhooks and Callbacks will be used

List of Product Fields

Products are used to describe the item that the customer is paying for within the application. This is typically used for record keeping and reporting. Below are the list of fields that can be configured for a product.

Param	Format	Description
currencyCode	String	The currency code for the amount
price	Number	The cost of the Product
quantity	Number	The number of units bought
sku	String	An identifier for the SKU, typically from the partners backend services
title	String	The name of the Product

List of Metadata Fields

Metadata fields can be used by the Partner to store any additional metadata that is not formally defined or needed by the Pay1st gateway.

Param	Format	Description
key	String	An identifiable key of this metadata field
value	String	The value of the metadata field

Example JSON Request

The following JSON Request is an example of the correct construction of a Create Payment Request:

{
    "countryCode": "NG",
    "currencyCode": "NGN",
    "amount": 100,
    "partnerReference": "1119bf84-dc97-4be9-aa67-ec27d7003f07",
    "callbackSuccessUrl": "https://callback.success",
    "callbackFailureUrl": "https://callback.failure",
    "callbackPendingUrl": "https://callback.pending",
    "callbackCancelUrl": "https://callback.cancel",
    "webhookUrl": "https://webhook.success",
    "products": [
        {
            "title": "10Credits",
            "sku": "12345",
            "price": 100,
            "quantity": 1,
            "currencyCode": "NGN"
        }
    ],
    "metadata": [
        {
            "key": "customerId",
            "value": "1"
        }
    ]
}

Success Response

Valid HTTP Success Status Codes:

HTTP Status Code	Name	Description
201	Success	This indicates that the request has been successful.
400	Bad Request	The `X-SIGNATURE`HTTP header in the request might not be matching the server. The `X-TIMESTAMP` HTTP header in the request might not be within 5 minutes of creating the Access Token. The Request Body might be invalid.

HTTP Response Body:

{
    "reference": "C-113976984708914-P",
    "partnerReference": "e27b3b79-5ab3-4c1b-806f-1428c08d8637",
    "countryCode": "NG",
    "currencyCode": "NGN",
    "amount": 100,
    "status": "NEW"
}

HTTP Response Fields

Name	Type	Description
amount	Number	This will match the amount of the original request
countryCode	String	This will match the countryCode of the original request
currencyCode	String	This will match the currencyCode of the original request
partnerReference	String	This will match the partnerReference of the original request
reference	String	This is the Pay1st identifier of this payment request
status	String	This represents the status of the payment. For all created payments, a value of `NEW` will be returned

Error Response

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