Fulfilment Completion Webhooks

Use this API to notify the Pay1st Gateway about successful fulfilment completion

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

API Description

HTTP Headers

Header NameDescription
AccessTokenThis is the Access Token field returned from the Authentication - Generate Access Token response. This should be in the format Bearer <AccessToken>
Content-Typeapplication/vnd.carry1st.payments.payment+json

URL Format

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

List of Fulfilment POST fields

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

ParamFormatMandatoryDescription
referencestringYesThe Pay1st reference returned in the Create Payment Request response (not your partnerReference)
productsarray of Product FieldsYesList 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

ParamFormatMandatoryDescription
skustringYesThe SKU of a product sent in the original payment request (maximum 20 characters). It must match that SKU exactly; otherwise the request is rejected with HTTP 404
fulfilmentReferencestringYesYour identifier for this fulfilment item (maximum 100 characters). It must be unique across all fulfilment items sent for the same transaction. A fulfilmentReference that has already been accepted for the transaction is rejected with HTTP 400
fulfilmentStatusstringYesStatus of the product fulfilment (e.g. FULFILLED). See List of Fulfilment Statuses below
quantityintegerYesNumber of units fulfilled
fulfilmentTimeStamplongYesUTC time when the product was fulfilled, as Unix epoch milliseconds (e.g. 1758441600000 = 2025-09-21T08:00:00Z). A value in seconds will be read as a date in January 1970.

Example JSON Request

The following JSON Request is an example of a correctly constructed Fulfilment Completion request. Replace the values in angle brackets with your own values.

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

List of Fulfilment Statuses

StatusDescription
NOT_STARTEDThe fulfilment has not started
PENDINGThe fulfilment is in currently in a pending on the partner system
PARTIALLY_FULFILLEDThe fulfilment has not fulfilled the entire quantity specified in the request
FULFILLEDThe SKU has been successfully fulfilled on the partner system
FAILEDThe fulfilment has failed on the partner system
REFUNDA refund has been issued for the partner
CHARGEBACKA chargeback has been issued for this SKU by the customer

Success Response

Valid HTTP Success Status Codes:

HTTP Status CodeNameDescription
204No ContentThis indicates that the request has been successful. No response body is returned. Treat any 2xx status code as success.
400Bad RequestThe request is invalid: a field is missing or invalid, the payment is not in SUCCESSFUL status, or a fulfilmentReference in the request has already been used for this transaction.
403ForbiddenThe transaction does not belong to your account.
404Not FoundNo transaction was found for reference, or a sku in the request is not part of the transaction.
401UnauthorizedThe AccessToken header is missing, invalid or expired, or your partner account is not active. Generate a new access token (see Authentication - Generate Access Token) and retry.
500Internal Server ErrorThis 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.