Skip to content
Cipay
Esc
↑↓navigate↵open⌘Jpreview

Create a public checkout

POST/v2/public/checkouts
Header parameters
idempotency-keystringrequired
Required for write endpoints that create records and need deterministic retry behavior.
min length 1 · max length 255
x-request-idstring
Optional caller-provided request correlation ID.
min length 1
Request body
requiredapplication/json
locatorstringrequired
min length 1 · max length 160
offerIdstring<uuid>required
formIdstring<uuid>
buyerobjectrequired
Show properties
namestring
min length 1 · max length 160
emailstring<email>required
max length 254
mobilestring
min length 1 · max length 32
localestring
Allowed:enar
billingAddressobject
Show properties
line1stringrequired
min length 1 · max length 200
line2string
min length 1 · max length 200
citystringrequired
min length 1 · max length 120
regionstringrequired
min length 1 · max length 120
postalCodestringrequired
min length 1 · max length 20
countryCodestring
min length 2 · max length 2 · default: "SA"
addressstring
min length 1 · max length 500
countrystring
min length 2 · max length 2
companyNamestring
min length 1 · max length 160
companyTaxNumberstring
min length 1 · max length 32
customAmountHalalasinteger
min 0 · max 9007199254740991
discountCodestring
max length 64 · matches ^[A-Z0-9_-]{1,64}$
policyFingerprintstring
matches ^[a-f0-9]{64}$
recurringConsentAcceptedany
Responses
200OK
checkoutobject | anyrequired
Show properties
Any of:
object
capabilitystringrequired
min length 32 · max length 512
orderIdstring<uuid>
productIdstring<uuid>
statusobjectrequired
Show properties
statestringrequired
Allowed:ready_for_checkouthosted_checkout_opencompletedfailedexpiredrecoverable
hostedUrlstring<uri> | anyrequired
Show properties
Any of:
string<uri>
string<uri>
any
any
expiresAtstring<date-time>required
nextActionstringrequired
Allowed:open_hosted_checkoutwaitdoneretrycontact_merchant
checkoutDesignobject | anyrequired
Show properties
Any of:
object
logoAssetIdstring<uuid> | any
Show properties
Any of:
string<uuid>
string<uuid>
any
any
accentColorany
backgroundColorany
textColorany
fontstringrequired
Allowed:systemarabic_sansserif
layoutstring
Allowed:two_columnstacked
productOrderstring<uuid>[]
max items 100
acceptsDiscountCodeboolean
default: false
copyobjectrequired
Show properties
headingobjectrequired
Show properties
enstringrequired
min length 1 · max length 120
arstringrequired
min length 1 · max length 120
subheadingobjectrequired
Show properties
enstringrequired
min length 1 · max length 120
arstringrequired
min length 1 · max length 120
submitLabelobjectrequired
Show properties
enstringrequired
min length 1 · max length 120
arstringrequired
min length 1 · max length 120
any
any
orderIdstring<uuid>
productIdstring<uuid>
any
any
400Standard Cipay error response.
errorobjectrequired
Show properties
codestringrequired
min length 1
messagestringrequired
min length 1
requestIdstringrequired
min length 1
detailsobject
404Standard Cipay error response.
errorobjectrequired
Show properties
codestringrequired
min length 1
messagestringrequired
min length 1
requestIdstringrequired
min length 1
detailsobject
409Standard Cipay error response.
errorobjectrequired
Show properties
codestringrequired
min length 1
messagestringrequired
min length 1
requestIdstringrequired
min length 1
detailsobject
422Standard Cipay error response.
errorobjectrequired
Show properties
codestringrequired
min length 1
messagestringrequired
min length 1
requestIdstringrequired
min length 1
detailsobject
429Standard Cipay error response.
errorobjectrequired
Show properties
codestringrequired
min length 1
messagestringrequired
min length 1
requestIdstringrequired
min length 1
detailsobject
500Standard Cipay error response.
errorobjectrequired
Show properties
codestringrequired
min length 1
messagestringrequired
min length 1
requestIdstringrequired
min length 1
detailsobject
Request
curl -X POST "https://api.cipay.net/v2/public/checkouts" \
  -H "idempotency-key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "locator": "string",
  "offerId": "<uuid>",
  "formId": "<uuid>",
  "buyer": {
    "name": "string",
    "email": "<email>",
    "mobile": "string",
    "locale": "en",
    "billingAddress": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "SA"
    },
    "address": "string",
    "country": "string",
    "companyName": "string",
    "companyTaxNumber": "string"
  },
  "customAmountHalalas": 0,
  "discountCode": "string",
  "policyFingerprint": "string",
  "recurringConsentAccepted": true
}'
Response
{
  "checkout": {
    "capability": "string",
    "orderId": "<uuid>",
    "productId": "<uuid>",
    "status": {
      "state": "ready_for_checkout",
      "hostedUrl": "<uri>",
      "expiresAt": "2024-01-01T00:00:00Z",
      "nextAction": "open_hosted_checkout",
      "checkoutDesign": {
        "logoAssetId": "<uuid>",
        "accentColor": "string",
        "backgroundColor": "string",
        "textColor": "string",
        "font": "system",
        "layout": "two_column",
        "productOrder": [
          "<uuid>"
        ],
        "acceptsDiscountCode": false,
        "copy": {
          "heading": {
            "en": "string",
            "ar": "string"
          },
          "subheading": {
            "en": "string",
            "ar": "string"
          },
          "submitLabel": {
            "en": "string",
            "ar": "string"
          }
        }
      },
      "orderId": "<uuid>",
      "productId": "<uuid>"
    }
  }
}