Checkout & Orders

Checkout

POST/api/v1/orders/checkout

Converts a shop's cart into an order and initiates payment. Idempotent — retrying an identical checkout request with the same idempotency key returns the original order instead of creating a duplicate.

Requires Authorization

Payment

Body parameters

`shopId`stringrequired	The shop being checked out — its cart must have at least one item.
`paymentMethod`stringrequired	e.g. MOBILE_MONEY.
`fulfillmentMethod`stringrequired	DELIVERY or PICKUP.
`deliveryAddress`string	10–300 characters. Required when fulfillmentMethod is DELIVERY.
`deliveryLatitude`number	Required when fulfillmentMethod is DELIVERY.
`deliveryLongitude`number	Required when fulfillmentMethod is DELIVERY.
`payerPhoneNumber`stringrequired	Mobile money number to charge.
`network`stringrequired	Mobile money provider.
`countryCode`stringrequired	ISO country code.
`currency`stringrequired	USD or CDF.

Notes

The order starts as AWAITING_PAYMENT and moves to PENDING_SELLER_REVIEW automatically once the payment provider confirms the charge.
Send an Idempotency-Key header to make retries safe.

Request

curl --request POST \
  --url https://api.swiftgoma.com/api/v1/orders/checkout \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "shopId": "<shopId>",
  "paymentMethod": "<paymentMethod>",
  "fulfillmentMethod": "<fulfillmentMethod>",
  "deliveryAddress": "<deliveryAddress>",
  "deliveryLatitude": "<deliveryLatitude>",
  "deliveryLongitude": "<deliveryLongitude>",
  "payerPhoneNumber": "<payerPhoneNumber>",
  "network": "<network>",
  "countryCode": "<countryCode>",
  "currency": "<currency>"
}'

201Example response

{
  "success": true,
  "data": {
    "id": "ord_5e6f7a",
    "buyerId": "3f2a1c9e",
    "shopId": "shop_2b3c4d",
    "status": "AWAITING_PAYMENT",
    "fulfillmentMethod": "DELIVERY",
    "paymentMethod": "MOBILE_MONEY",
    "currency": "USD",
    "deliveryAddress": "12 Avenue du Lac, Goma",
    "deliveryFee": "2.00",
    "subtotal": "25.00",
    "total": "27.00",
    "items": [
      {
        "id": "oitem_1a2b3c",
        "productId": "prod_7c8d9e",
        "variantId": "var_4d5e6f",
        "name": "Riz parfumé 25kg",
        "quantity": 2,
        "unitPrice": "12.50",
        "lineTotal": "25.00"
      }
    ],
    "createdAt": "2026-02-15T09:00:00.000Z",
    "updatedAt": "2026-02-15T09:00:00.000Z"
  }
}