🚧

Authentication

Before you continue, we recommend reading the authentication section first to understand how to authorize your requests.

This guide covers how to create orders for your customers. Orders are a seamless way to initiate different payments and help collect customer information.

Follow these steps to create an order for your customer's payments

1. Encrypt the create order request. This request should contain the customer's information (firstname, lastname, mobile, country and email) and transaction details (amount, reference, currency and description).
2. Send the encrypted request to the create order endpoint.

Here are some samples to help you create orders:

{
   "customer":{
      "firstname":"ideos",
      "lastname":"pay",
      "mobile":"+23481582333444",
      "country":"NG",
      "email":"[email protected]"
   },
   "order":{
      "amount":100,
      "reference":"ORD001",
      "description":"Pay",
      "currency":"NGN"
   },
   "payment":{
      "RedirectUrl":"https://www.hi.com"
   }
}

{
    "data": "b6t36QfBWy0r7SQipdgkzp1+5O43QyYYjrj8FNIAKfx7gR9AtITHEDDA02m3oLqFNwsButeKkyZVL8+21kz9sY1yfJuI/QqtefxGPUagYCnuMNIBFeo97rWCemI8oBQ5G33NgnPoX54MWw7aZ8/W8wLWtrAeFA1WjwsIh3Ewb7z07Q/IgqCXn6793xizC9qIp/X5HCzdnBgUcUk92Xo7qKPbsR/8Cvmg6zapU9Z8zsdYwxUx/lkQLAihvarQ7LmGL4tyijKu2FcNQL7xdJKArl1hfv4d80FkD/0tnbxl6w/taL2rCgvALiNvgerxJQi8PgMACG4lMzib+LVhNzcu94fmUNiG7kwUfbB7QmlUmqgGoyMwOqSGGbKDkNcyQQuVPbaW6znfIGIqp3sVFBLnMD9vCWdlIqmNTskp2ROBL4DVAzNmJwAj9ofhXcSN5RF1Bx0ubAzQ4N90z6xduwZHH/iV/rqTfsIdXkRDVZWP25cJB8huoTTJcBBnoX9bFnj1709fAGQuMyNlj+uBqXKwFA6Q9MrafefNnRzU6OpeNzibNpL3hOHfoZkuA8Zqjc14Rq1BuIMYuLrsfpdZTW2vSnNWUju5B+DU9sat5Sbxks6QqIyrH3HhzJQeCaD59ruFDTyAG/kSz37y18BTt3iybg0z+nW1zXWfJec46hSCDpQ="
}

{
  "data": {
    "order": {
      "reference": "754874724",
      "processorReference": "IDSPAY-76279490-6B08-45CF-9919-582E9C77F52B",
      "orderPaymentReference": null,
      "amount": 100,
      "fee": 0,
      "feeRate": 0,
      "statusId": 1,
      "status": "Initiated",
      "currency": "NGN",
      "narration": "Pay"
    },
    "subsidiary": {
      "id": 1,
      "name": "Test Merchant",
      "country": "NG",
      "supportEmail": "[email protected]",
      "customization": []
    },
    "customer": {
      "email": "[email protected]",
      "firstName": "ideos",
      "lastName": "pay",
      "mobile": "+23481582333444",
      "country": "NG"
    },
    "payment": {
      "code": null,
      "source": "Selected by Customer",
      "selectedOption": null,
      "accountNumber": null,
      "bankProviderName": null
    },
    "otherPaymentOptions": [
      {
        "code": "BT",
        "name": "Bank Transfer",
        "currency": "NGN"
      },
      {
        "code": "C",
        "name": "Card Payment",
        "currency": "NGN"
      },
      {
        "code": "BA",
        "name": "Bank Account",
        "currency": "NGN"
      },
      {
        "code": "USSD",
        "name": "USSD",
        "currency": "NGN"
      },
      {
        "code": "BANK-TRANSFER",
        "name": "Pay With Bank Transfer",
        "currency": "NGN"
      },
      {
        "code": "NQR",
        "name": "QR Code Payment",
        "currency": "NGN"
      }
    ],
    "savedCards": [],
    "subsidiaryOrderSummary": {
      "orderName": "Test Merchant Order 754874724",
      "totalAmount": 100,
      "reference": "754874724",
      "currency": "NGN",
      "orderItems": [
        {
          "name": "Summary",
          "amount": 100
        }
      ]
    }
  },
  "status": "success",
  "statusCode": "01",
  "message": "Created order successfully"
}

After creating an order, you can now initiate a payment on the order. Learn how to initiate payments here.

Supported Modes for creating an Order

You can create your order to support different payment flows and types. Orders now support single payments, recurring payments, and payments via links.

Payment links

To create an order with a payment link, you need to link the paymentLinkId to the order. First, create the payment link (see more details here) then include the link's ID in your order request.

📘

You can retrieve the payment link details by passing the paymentLinkReferencefrom the response into the fetch payment link endpoint.

{
    "customer": {
        "firstname": "King",
        "lastname": "James",
        "mobile": "+2348158200000",
        "country": "NG",
        "email": "[email protected]"
    },
    "order": {
        "amount": 200,
        "reference": "abc0923",
        "description": "Test Order",
        "currency": "USD"
    },
    "payment": {
        "redirectUrl": "https://www.hello.com",
        "paymentLinkId": 1
    },
    "paymentMeta": {
        "ipAddress": "127.0.0.0",
        "userAgent": "Chrome/129.0.0.0"
    }
}

{
    "data": "b6t36QfBWy0r7SQipdgkzp1+5O43QyYYjrj8FNIAKfx7gR9AtITHEDDA02m3oLqFNwsButeKkyZVL8+21kz9sY1yfJuI/QqtefxGPUagYCnuMNIBFeo97rWCemI8oBQ5G33NgnPoX54MWw7aZ8/W8wLWtrAeFA1WjwsIh3Ewb7z07Q/IgqCXn6793xizC9qIp/X5HCzdnBgUcUk92Xo7qKPbsR/8Cvmg6zapU9Z8zsdYwxUx/lkQLAihvarQ7LmGL4tyijKu2FcNQL7xdJKArl1hfv4d80FkD/0tnbxl6w/taL2rCgvALiNvgerxJQi8PgMACG4lMzib+LVhNzcu94fmUNiG7kwUfbB7QmlUmqgGoyMwOqSGGbKDkNcyQQuVPbaW6znfIGIqp3sVFBLnMD9vCWdlIqmNTskp2ROBL4DVAzNmJwAj9ofhXcSN5RF1Bx0ubAzQ4N90z6xduwZHH/iV/rqTfsIdXkRDVZWP25cJB8huoTTJcBBnoX9bFnj1709fAGQuMyNlj+uBqXKwFA6Q9MrafefNnRzU6OpeNzibNpL3hOHfoZkuA8Zqjc14Rq1BuIMYuLrsfpdZTW2vSnNWUju5B+DU9sat5Sbxks6QqIyrH3HhzJQeCaD59ruFDTyAG/kSz37y18BTt3iybg0z+nW1zXWfJec46hSCDpQ="
}

{
    "data": {
        "order": {
            "reference": "abc0923",
            "processorReference": "ALP-011947D8E93C11EF8D76024163CF7247",
            "orderPaymentReference": null,
            "amount": 200.0000,
            "fee": 0.0000,
            "feeRate": null,
            "statusId": 1,
            "status": "Initiated",
            "currency": "USD",
            "narration": "Pay",
            "paymentLinkId": 1,
            "recurringPaymentId": null,
            "paymentLinkReference": "APaspsWfVYh6r8AIOO85h4iqMki2JR5SDLhGK3PS94ESr7l1JsYxdiABM112",
            "recurringPaymentReference": null
        },
        "subsidiary": {
            "id": 1,
            "name": "AlliancePay",
            "country": "NG",
            "supportEmail": "[email protected]",
            "customization": []
        },
        "customer": {
            "email": "[email protected]",
            "firstName": "firstname",
            "lastName": "lastname",
            "mobile": "+2348158200000",
            "country": "NG"
        },
        "payment": {
            "code": null,
            "source": null,
            "selectedOption": null,
            "accountNumber": null,
            "bankProviderName": null
        },
        "otherPaymentOptions": [
            {
                "code": "C",
                "name": "Card Payment",
                "currency": "USD"
            }
        ],
        "savedCards": [],
        "subsidiaryOrderSummary": {
            "orderName": "AlliancePay Order abc0923",
            "totalAmount": 200.0,
            "reference": "abc0923",
            "currency": "USD",
            "orderItems": [
                {
                    "name": "Summary",
                    "amount": 200.0
                }
            ]
        }
    },
    "status": "success",
    "statusCode": "01",
    "message": "Created order successfully"
}

Recurring or Subscription payments

To create a subscription payment:

1. Define the frequency of your subscription payments e.g. if you want to collect weekly payments, set the weekly frequencyId in your request. You can fetch all supported IDs from the frequencies endpoint .
   cURL200 OK

   curl --location 'https://checkout-api-service-main.prod-alliancepay.com/checkout/frequencies' \
   --header 'api-key: YOUR_PUBLIC_KEY' \
   --data ''

   {
       "data": [
           {
               "hours": 1,
               "days": 0,
               "name": "Hourly",
               "description": "Payment made hourly",
               "isActive": null,
               "id": 1,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 24,
               "days": 1,
               "name": "Daily",
               "description": "Daily",
               "isActive": null,
               "id": 2,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 168,
               "days": 7,
               "name": "Weekly",
               "description": "Weekly",
               "isActive": null,
               "id": 3,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 336,
               "days": 14,
               "name": "Bi-Weekly",
               "description": "Bi-Weekly",
               "isActive": null,
               "id": 4,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 504,
               "days": 21,
               "name": "Every 3 Weeks",
               "description": "Every 3 Weeks",
               "isActive": null,
               "id": 5,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 720,
               "days": 30,
               "name": "Monthly",
               "description": "Monthly",
               "isActive": null,
               "id": 6,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 1440,
               "days": 60,
               "name": "Bi-Monthly",
               "description": "Bi-Monthly",
               "isActive": null,
               "id": 7,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 2160,
               "days": 90,
               "name": "Every 3 Months",
               "description": "Every 3 Months",
               "isActive": null,
               "id": 8,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 4320,
               "days": 180,
               "name": "Every 6 Months",
               "description": "Every 6 Months",
               "isActive": null,
               "id": 9,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 8760,
               "days": 365,
               "name": "Yearly",
               "description": "Yearly",
               "isActive": null,
               "id": 10,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           },
           {
               "hours": 17520,
               "days": 730,
               "name": "Bi-Yearly",
               "description": "Bi-Yearly",
               "isActive": null,
               "id": 11,
               "dateCreated": "2023-07-06T08:48:45",
               "dateUpdated": null,
               "dateDeleted": null,
               "createdBy": -1,
               "updatedBy": null,
               "deletedBy": null
           }
       ],
       "status": "success",
       "statusCode": "00",
       "message": "Operation successful"
   }

2. Collect your customer's information for the order. Add their name, mobile, country and email in your request.
   Example

   {
       "customer": {
           "firstname": "John",
           "lastname": "Jones",
           "mobile": "+2348158200000",
           "country": "NG",
           "email": "[email protected]"
       },
       "order": {}, //updated in step 3
       "payment": {},
       "paymentMeta": {}
   }

3. Specify the order information. Key details to include in your order object are: amount, reference, currency and the order description.
   Example

   {
       "customer": {
           "firstname": "John",
           "lastname": "Jones",
           "mobile": "+2348158200000",
           "country": "NG",
           "email": "[email protected]"
       },
       "order": {
           "amount": 200,
           "reference": "123456789",
           "description": "",
           "currency": "USD"
       },
       "payment": {}, //updated in step 4
       "paymentMeta": {}  //updated in step 4
   }

4. Use the frequencyId parameter (from step 1) to set up recurring charges in a specific currency. For example, the request below charges a customer weekly. To limit the number of charges, use the numberOfPayment parameter.
   Recurring sampleRecurring sample with limit

    {
       "customer": {
           "firstname": "John",
           "lastname": "Jones",
           "mobile": "+2348158200000",
           "country": "NG",
           "email": "[email protected]"
       },
       "order": {
           "amount": 200,
           "reference": "123456789",
           "description": "",
           "currency": "USD"
       },
       "payment": {
           "RedirectUrl": "https://www.google.com",
           "frequencyId": 1
       },
       "paymentMeta": {
           "ipAddress": "127.0.0.0",
           "userAgent": "Chrome/129.0.0.0"
       }
   }

   {
       "customer": {
           "firstname": "John",
           "lastname": "Jones",
           "mobile": "+2348158200000",
           "country": "NG",
           "email": "[email protected]"
       },
       "order": {
           "amount": 200,
           "reference": "123456789",
           "description": "",
           "currency": "USD"
       },
       "payment": {
           "RedirectUrl": "https://www.google.com",
           "frequencyId": 1, // charge customer daily
           "numberOfPayment": 30 // charge customer 30 times
       },
       "paymentMeta": {
           "ipAddress": "127.0.0.0",
           "userAgent": "Chrome/129.0.0.0"
       }
   }

5. Encrypt your request and send the encrypted payload to the create order endpoint
   Sample request (encrypted)200 OK

   {
       "data": "Roq5u7XgGBs10gKrKYV0k9tb3JQeOdaCBeUPXGFkSlw2JCPsWl10p6dX8ZXsNaPE7RNUPy21BGzzfSHuBJm2N86AE2pNocLsodt6+EOLlYWxvCMuhygRFwQU8gSFiIMrCPMooiNNBgSboMracwUc8pdNHsUni9bkHq7dXxC+V2H1aMzdUqJOtKQSHpZvo0ZNIUSQGzhRGU/ZiTOlX3m5Xd4R+ZUoevZyI/3aZHI4HAtazvtfDxqKNPVB5mJqEA7ifh/EF9Don7mC+1QTSpkJ6TV1i4YjHDPoTReN4u6KWorLLJHjSjvDmlgPh60mHkV8wr27gaxeFctEPPFdZ7S8d0onaI9aXzpa/iI0TUhfrfzoScVeO5mgtEnxUvSpOzEPJClDQ+Dcbpz9j6YjT7ZsqtEa0hkOZ5mBzPBVmCSGsATNiXdRtPc0AhJL1W3j9mf2KVto+ZkF8ShE6VAVgFplutIbQ4P2378DVQvR8njOFjLh/j2+6knILmAu+jqjVZPAN4ItDXc6KXd5ZaRoWTeMY8CwnysYrwFSI8XqZDot3Go596bMe+B8fGEn0kyK3ApYvBemD4GkGQfELfP3NlKT/thrvBuXSQCxjBAjXp4bfXRGtX311ijfFN91wMIrPPCYYTJtlcf5+QzOMFdiRj+r0NsbGqXYZs8tlvGbROVGkJzgkOn+JMOFmibOwe0NZWUsPB/hDimNVU4SbzkS7incwLosVDHSFMP1cYDo9GOu1G+y75MLWcz7WmjaQsmc5L76SL18RSnnnmARC4cAlxo9mXVO5tx5oCFnSURIjrDCSKjmGXb+rOKIEIDdF5eSaHU+Yx43npCyAmQNRMB4/Rm6qxnuIe9TXDE+oxuH1kSdtfD4G8yn9SubZba6/Ykx7A5ZMIZdvQQAnLQ3eCOS8WLVWhmXghahN+4X7ISJNtOPFAaPLlckNCc+9VmChfeiJHKNXoSDU9PPA8+8CtzDPdRKminuNiyHPgeskZN5A1QZC2UCP1V6ivSzk/ySfIzY7uW2pAsk+14b9ZNjic8FJVpc+ToHpilGiCrMMIVtSZ24qVONoFT48OZA0ogTvIZyfyw6KRvaZfU1SuQpJaBu5qh21mH0SgUNj5UfXHWfZhpwjkIoyAo6ikU9waCOqx0N86Ii8N+oQwseTcIC8GI1V2PCx8I85E2+3moOzdNQUdSuH5ZBQZV+pf8ghrKEmkZIwaWFL/9pMN26MehSIJ9sYSDD67FIFFEMVL/blmMbqzl8lXIOO7bdIN7LvlmgzwN7NuH+dL+F4RghQWrQ0h0pt541aELy+p5wls4XOVTWqvYdCWYnNRI3sRcRRYDlN3e1xfOOMSdkGcB0iKcS8c+IB8XiqQ=="
   }

   {
       "data": {
           "order": {
               "reference": "992046078",
               "processorReference": "ALP-5DBBE3AEF03911EF8D76024163CF7247",
               "orderPaymentReference": null,
               "amount": 200.0000,
               "fee": 0.0000,
               "feeRate": null,
               "statusId": 1,
               "status": "Initiated",
               "currency": "USD",
               "narration": "Pay",
               "paymentLinkId": null,
               "recurringPaymentId": null,
               "paymentLinkReference": null,
               "recurringPaymentReference": null
           },
           "subsidiary": {
               "id": 1,
               "name": "AlliancePay",
               "country": "NG",
               "supportEmail": "[email protected]",
               "customization": []
           },
           "customer": {
               "email": "[email protected]",
               "firstName": "John",
               "lastName": "Jones",
               "mobile": "+2348158200000",
               "country": "NG"
           },
           "payment": {
               "code": null,
               "source": null,
               "selectedOption": null,
               "accountNumber": null,
               "bankProviderName": null
           },
           "otherPaymentOptions": [
               {
                   "code": "C",
                   "name": "Card Payment",
                   "currency": "USD"
               }
           ],
           "savedCards": [],
           "subsidiaryOrderSummary": {
               "orderName": "AlliancePay Order 992046078",
               "totalAmount": 200.0,
               "reference": "992046078",
               "currency": "USD",
               "orderItems": [
                   {
                       "name": "Summary",
                       "amount": 200.0
                   }
               ]
           }
       },
       "status": "success",
       "statusCode": "01",
       "message": "Created order successfully"
   }