Overview

An Order Completion request needs to be made in order to distribute the Product’s digital content to the customer. This API is a POST request that takes order details as input, and returns order 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 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.order.distributor+json`
X-SIGNATURE	This is the header that will contain the signature of the request. Refer to Generating Signatures
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

POST api/orders/distributors/order-complete

List of Order Complete POST fields

These are the list of POST payload fields that needs to be submitted to the API

Param	Format	Mandatory	Description
externalReference	String	Y	The `externalReference` of the distributor that is used for reconciliation as well as identifying the order on the Flow1st Partner System
productBundleSku	String	Y	This is the SKU identifier that is retrieved from the List Product Fields API
quantity	Number	Y	This should always be 1
recipientIdentifier	String	Y	The userId of the customer that exists on the platform of the Product
email	String	Y	The email of the customer to send the Order Email
webhookUrl	String		If provided, this is the URL that will be used to notify the partner backend server of order completion events. If not present, the default value in Configuring Webhooks will be used

Example JSON Request

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

{
   "externalReference": "saqr_ref_001",
   "productBundleSku": "codm30cp",
   "quantity": 1,
   "recipientIdentifier": "GEDKZW",
   "email": "[email protected]",
   "webhookUrl": "https://86c99ac283b8.ngrok-free.app"
}

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-58333198548871-P",
   "externalReference": "saqr_ref_002",
   "productBundleSku": "codm30cp",
   "quantity": 1,
   "recipientIdentifier": "GEDKZW",
   "email": "[email protected]",
   "status": "PENDING",
   "fulfilmentStatus": "PENDING"
}

HTTP Response Fields

Name	Type	Description
reference	String	The Carry1st Order reference for this order
externalReference	String	This will match the `externalReference` of the original request
productBundleSku	String	This will match the `productBundleSku` of the original request
quantity	Number	This will match the quantity of the original request
email	String	This will match the email of the original request
status	String	This represents the status of the order. For all created payments, a value of `PENDING` will be returned
fulfilmentStatus	String	This represents the status of the order. For all created payments, a value of `PENDING` will be returned

Error Response

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