QorePay logo
QorePay logo

Create a purchase – the main request for any e-commerce integration.



To run payments in your application use POST /purchases/, request to register payments and receive the checkout link (checkout_url). After the payment is processed, gateway will redirect the client back to your website (take note of success_redirect ,failure_redirect).

You have three options to check payment status: 1) use success_callback parameter of Purchase object; 2) use GET /purchases/purchase_id/ request; 3) set up a Webhook using the UI or Webhook API to listen topurchase.paid or purchase.payment_failure event on your server.

In case making a purchase client agrees to store his card for the upcoming purchases, next time he will be able to pay in a single click.

Instead of a redirect you can also utilize Direct Post checkout: you can create an HTML formon your website with method="POST" and action pointing to direct_post_urlof a created Purchase. You will also need to saturate form with inputfor card data fields. As a result, when a payer submits their card data, it will be posted straight to our system, allowing you to customize the checkout as you wish while your PCI DSS requirement is only raised to SAQ A-EP, as your system doesn't receive or process card data. For more details, see the documentation on Purchase's direct_post_url field.

To pay for test Purchases, use 4444 3333 2222 1111 as the card number, 123 as CVC, any date/month greater than now as expiry and any (Latin) cardholder name. Any other card number/CVC/expiry not greater or equal than the current month will all fail a test payment.


  • authorization



    Set value to BEARER SECRET_KEY

  • content-type



    Set value to JSON


  • brand_id



    ID of the brand to create this Purchase for. You can copy it down in the API section, see the &quotspecify the ID of the Brand" link in answer to &quotHow to setup payments on website or in mobile app?&quot.

  • client



    Contains details about the client of a purchase or payment - the remote payer/fund recipient party. Either this or client_id is required.

  • purchase



    Core information about the Purchase, including the products, total, currency and invoice fields. If you're using invoicing via /billing/ or /billing_templates/, this object will be copied 1:1 from BillingTemplate you specify to the resulting Purchases (also to subscription Purchases).

  • client_id

    string | null

    ID of a Client object used to initialize ClientDetails (.client) of this Purchase. Either this field or specifying.client object is required (you can only specify a value for one of these fields). All ClientDetails fields from the Client will be copied to .client object. Note that editing Client object won't change the respective fields in already created Purchases.

    If you specify this field and your client saves a recurring_token (for instance, by saving their card), the respective ClientRecurringToken will be created. See the/clients/$id/recurring_tokens/ endpoint.

  • send_receipt


    Whether to send receipt email for this Purchase when it's paid.

  • reference


    Invoice reference.

  • payment_method_whitelist

    array of strings

    An optional whitelist of payment methods availble for this purchase. Use this field if you want to restrict your payer to pay using only one or several specific methods.

    Using this field and at the same time trying to use specific capabilities of a Purchase (e.g. charging it using a saved card token using POST /purchases/$id/charge/) can cause a situation when there are no payment methods available for paying this Purchase. This will cause a validation error on Purchase creation. Please check theGET /payment_methods/ response for your desired Purchase parameters and/or consult with your account manager.

  • success_redirect


    When Purchase is paid for successfully, your customer will be taken to this link. Otherwise a standard screen will be displayed.

  • failure_redirect


    If there's a payment failure for this Purchase, your customer will be taken to this link. Otherwise a standard screen will be displayed.

  • cancel_redirect


    If you provide this link, customer will have an option to go to it instead of making payment (a button with 'Return to seller' text will be displayed). Can't contain any of the following symbols: <>'".

    Be aware that this does not cancel the payment (e.g. does not do the equivalent of doing the POST /purchases/$id/cancel/request ); the client will still be able to press 'Back' in the browser and perform the payment.

  • success_callback


    When Purchase is paid for successfully, the success_callback URL will receive a POSTrequest with the Purchase object's data in body.


  • 201


  • 400

    Invalid data submitted or request processing error



const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json'
  body: JSON.stringify({
    client: {
      email: '[email protected]',
      phone: '+2349053693367',
      full_name: 'Felix Qorepay',
      street_address: '20 Kigali road.',
      country: 'NG',
      city: 'Yaba'
    purchase: {
      products: [
          quantity: '2',
          name: 'Dog food',
          price: 230000
    send_receipt: true, 
    brand_id: '4343434344334343434',
    success_redirect: 'https://www.qore.test',
    failure_redirect: 'https://www.qore.test.fail'

fetch('https://gate.qorepay.com/api/v1/purchases/', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Sample Response


  "type": "string",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_on": 1619740800,
  "updated_on": 1619740800,
  "client": {
    "bank_account": "string",
    "bank_code": "string",
    "email": "[email protected]",
    "phone": "+234906435664",
    "full_name": "string",
    "personal_code": "string",
    "street_address": "string",
    "country": "st",
    "city": "string",
    "zip_code": "string",
    "state": "string",
    "shipping_street_address": "string",
    "shipping_country": "st",
    "shipping_city": "string",
    "shipping_zip_code": "string",
    "shipping_state": "string",
    "cc": [
      "[email protected]"
    "bcc": [
      "[email protected]"
    "legal_name": "string",
    "brand_name": "string",
    "registration_number": "string",
    "tax_number": "string"
  "purchase": {
    "currency": "str",
    "products": [
        "name": "string",
        "quantity": "1",
        "price": 0,
        "discount": 0,
        "tax_percent": "0",
        "category": "string"
    "total": 0,
     "notes": "string",
    "debt": 0,
    "subtotal_override": null,
    "total_tax_override": null,
    "total_discount_override": null,
    "total_override": null,
    "request_client_details": [],
    "timezone": "Europe/Oslo",
    "due_strict": false,
    "email_message": "string"
  "payment": {
    "is_outgoing": false,
    "payment_type": "purchase",
    "amount": 0,
    "currency": "str",
    "net_amount": 0,
    "fee_amount": 0,
    "pending_amount": 0,
    "pending_unfreeze_on": 1619740800,
    "description": "string",
    "paid_on": 1619740800,
    "remote_paid_on": 1619740800
  "issuer_details": {
    "website": "string",
    "legal_street_address": "string",
    "legal_country": "st",
    "legal_city": "string",
    "legal_zip_code": "string",
    "bank_accounts": [
        "bank_account": "string",
        "bank_code": "string"
    "legal_name": "string",
    "brand_name": "string",
    "registration_number": "string",
    "tax_number": "string"
  "transaction_data": {
    "payment_method": "string",
    "extra": {},
    "country": "string",
    "attempts": [
        "type": "execute",
        "successful": true,
        "payment_method": "string",
        "extra": {},
        "country": "string",
        "client_ip": "string",
        "processing_time": 1619740800,
        "error": {
          "code": "string",
          "message": "string"
  "status": "created",
  "status_history": [
      "status": "created",
      "timestamp": 1619740800,
      "related_object": {
        "type": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  "viewed_on": 1619740800,
  "company_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "is_test": true,
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "brand_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "billing_template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "client_id": null,
  "send_receipt": false,
  "is_recurring_token": true,
  "recurring_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  
  "reference_generated": "string",
  "reference": "string",
  "issued": "2020-04-30",
  "due": 1619740800,
  "refund_availability": "all",
  "refundable_amount": 0,
  "currency_conversion": {
    "original_currency": "string",
    "original_amount": 0,
    "exchange_rate": 0
  "payment_method_whitelist": [
  "success_redirect": "string",
  "failure_redirect": "string",
  "cancel_redirect": "string",