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
- An access token needs to be generated in order to use this API (see Authentication - Generate Access Token)
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 |
URL Format
https://<payments_url>/api/pay1st/payments/fulfilmentsList of Fulfilment 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 | The Pay1st reference returned in the Create Payment Request response (not your partnerReference) |
| 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 | The 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 |
| fulfilmentReference | string | Yes | Your 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 |
| fulfilmentStatus | string | Yes | Status of the product fulfilment (e.g. FULFILLED). See List of Fulfilment Statuses below |
| quantity | integer | Yes | Number of units fulfilled |
| fulfilmentTimeStamp | long | Yes | UTC 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
| 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 |
|---|---|---|
| 204 | No Content | This indicates that the request has been successful. No response body is returned. Treat any 2xx status code as success. |
| 400 | Bad Request | The 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. |
| 403 | Forbidden | The transaction does not belong to your account. |
| 404 | Not Found | No transaction was found for reference, or a sku in the request is not part of the transaction. |
| 401 | Unauthorized | The 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. |
| 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.
