QorePay - Api Documentation

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

POST

https://gate.qorepay.com/api/v1/purchases/

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.

HEADER PARAMS

authorization

String

required
Set value to BEARER SECRET_KEY

content-type

String

required
Set value to JSON

REQUEST BODY

brand_id

string

required
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

Object

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

string

required
The client's email address
phone

string

The client's phone number in the country_code number format. Eg. +2349010010010
full_name

string

Client's full name
street_address

string

Street house number and flat address where applicable.
country

string

Country code in the ISO 3166-1 alpha-2 format (e.g. NG)
city

string

City name e.g Yaba
country

string

Country code in the ISO 3166-1 alpha-2 format (e.g. NG)
purchase

Object

required
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).
currency

string

Currency code in the ISO 4217 standard (e.g. 'NGN').
products

array of objects

required
Line items of the invoice. In case of a transaction with no invoice sent, specify a single Product forming the cost of transaction.
PRODUCT OBJECT []
name

string

required
Currency code in the ISO 4217 standard (e.g. 'NGN').
price

integer

required
Amount of money as the smallest indivisible units of the currency. Example: 1 kobo for NGN. (100 = 1NGN)
quantity

string

Quantity of these products in invoice, where default value is 1 and minimum is 0.
discount

integer

Amount of money as the smallest indivisible units of the currency. Example: 1 kobo for NGN. (100 = 1NGN)
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

boolean

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

string

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

url

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

url

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

url

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

url

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

RESPONSES

201

OK

400

Invalid data submitted or request processing error

Query

Javascript


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

JSON


{
  "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": [
    "string"
  ],
  "success_redirect": "string",
  "failure_redirect": "string",
  "cancel_redirect": "string",