Used in Gateway Integration

Overview

As Carry1st maintains the responsibilities of Merchant of Record status, it’s important that Carry1st can verify that each order has been fulfilled via the Fulfilment Completion Webhooks. This API is a POST request that takes the Carry1st reference, fulfilled products and SKUs as input. The Pay1st Gateway responds with an empty 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/fulfilments

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
reference	string	Yes	Unique identifier for the transaction
products	array of Product Fields	Yes	List of product items to be fulfilled

List of Product Fields

Products are used to describe the item that the customer is paying for within the application. These are the products and SKUs that were actually fulfilled

Param	Format	Mandatory	Description
sku	string	Yes	Identifier for the specific product SKU
fulfilmentReference	string	Yes	The identifier of the fulfilment reference
fulfilmentStatus	string	Yes	Status of the product fulfilment (e.g. FULFILLED)
quantity	integer	Yes	Number of units fulfilled
fulfilmentTimeStamp	long UTC	Yes	UTC timestamp when the product was fulfilled. This should be in Linux epoch format

Example JSON Request

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

{
    "reference": "<carry1st_transaction_reference>",
    "products": [
        {
            "sku": "SKU_1",
            "fulfilmentReference": "<partner_fulfilment_reference_1",
            "fulfilmentStatus": "FULFILLED",
            "quantity": 1,
            "fulfilmentTimeStamp": <long UTC>
        },
        {
            "sku": "SKU_2",
            "fulfilmentReference": "<partner_fulfilment_reference_2",
            "fulfilmentStatus": "FULFILLED",
            "quantity": 1,
            "fulfilmentTimeStamp": <long UTC>
        }
    ]
}

List of Fulfilment Statuses

Status	Description
NOT_STARTED	The fulfilment has not started
PENDING	The fulfilment is in currently in a pending on the partner system
PARTIALLY_FULFILLED	The fulfilment has not fulfilled the entire quantity specified in the request
FULFILLED	The SKU has been successfully fulfilled on the partner system
FAILED	The fulfilment has failed on the partner system
REFUND	A refund has been issued for the partner
CHARGEBACK	A chargeback has been issued for this SKU by the customer

Success Response

Valid HTTP Success Status 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 )
500	Internal Server Error	This would be an error on the Carry1st side. Carry1st Team will be aware of this, but the Partner might want to follow up on this error.

HTTP Response Body

There is no response body sent by the Pay1st Gateway

Error Response

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