Skip to main content
Collect local and international card payments from your customers using our integration. EPayClub API helps you to accept payment from Mastercard, Visa, AMEX and JCB cards.
Our APIs only support online payments for single and recurring payments. We do not support contactless payments (NFC technology) or POS transactions.

​
Payment flow

Several steps occur between entering your card details online and seeing the charge on your account. Before we cover the steps involved in the charge, let’s review some terminology:
  1. Cardholder: This refers to the customer making the payment with their card.
  2. Authorization model (Auth Models): Defines how a customer approves a card payment.
We’ll proceed assuming you’ve already set up a customer order. If you need to create one, you’ll find the steps here.
Payment flowchart

​
Single Card Payments

In this section, we’ll cover the basics of making one-time card payments. This is great for checkout experiences and other one-time payment use cases. After creating the order, you need to follow these steps to complete the card payment.
  1. Collect the customer’s card information.
  2. Encrypt sensitive data within your request.
  3. Guide the customer through the payment authorization process using the required method.
  4. Confirm the payment and inform the customer of its outcome.

​
Collecting the Customer’s Card Information

Present the customer with a secure form to gather their card details. These details are crucial for initiating the transaction and consist of:
Customer informationParameterExampleRequired
Card numbercard.cardnumber5555555555554444Yes
Card expiry monthcard.expirymonth12Yes
Card expiry yearcard.expiryyear27Yes
Card security code (CVV / CVC)card.cvv123Yes
Street addressbillingAddress.street58 Blatchington RdYes
CitybillingAddress.cityHoveYes
StatebillingAddress.stateEast SussexYes
CountrybillingAddress.countryGBYes
Zip codebillingAddress.zipCodeBN3 3YHYes
Combine the card data, order reference, paymentoption, and the customer’s country. Encrypt the request before sending it to the pay order endpoint. 
{
    "reference": "12345678",
    "paymentoption": "C",
    "country": "GB",
    "card": {
        "cardnumber": "5555555555554444",
        "expirymonth": "12",
        "expiryyear": "27",
        "cvv": "123",
       "billingAddress": {
            "street": "58 Blatchington Rd",
            "city": "Hove",
            "country": "GB",
            "state": "East Sussex",
            "zipCode": "BN3 3YH"
        }
    }
}
Upon receiving your request, we will return a successful response containing the authorization instructions for the customer to complete payment.
200 OK
{
  "data": {
    "paymentDetail": {
      "redirectUrl": "https://core-api-service.ideospay.dev/web/card/authorize/CPF046D30F-3F82-4A9A-B2AD-AC5AE3480D8F/initiate",
      "recipientAccount": null,
      "paymentReference": "CPF046D30F-3F82-4A9A-B2AD-AC5AE3480D8F"
    },
    "bankTransferDetails": null,
    "orderPayment": {
      "orderId": 26,
      "orderPaymentReference": "PGW-PAYREF-96C2ABCB218C43329037E47268F74195",
      "currency": "NGN",
      "statusId": 2,
      "orderPaymentResponseCode": "02",
      "orderPaymentResponseMessage": "pending-authenticaion",
      "orderPaymentInstrument": null,
      "remarks": "Order payment initiated",
      "totalAmount": 114,
      "fee": 14
    }
  },
  "status": "success",
  "statusCode": "02",
  "message": "Card order created successfully"
}

​
Authorization models

Cardholder authorization is required to finalize the payment. While various methods exist, EPayClub offers two distinct authorization models:
  1. Challenged flow or 3DS
  2. Non-challenged authorization or noauth

​
Challenged flow / 3DS

With this model, the customer is securely redirected to their bank’s authorization page. The bank will request varying information, such as a soft token, one-time password, or address. In some cases, a passphrase may be required. Open the paymentDetail.redirectUrl to send the customer to their bank’s page for payment authorization. If the payment is authorized successfully, EPayClub gets notified of the successful payment, and you receive a webhook containing the transaction details. For failed payments, you will receive a separate webhook with the final payment status.

​
Non-challenged flow / NoAuth

2DS or Noauth payments are unchallenged card transactions, i.e. the customer is not required to authorize the charge to complete them. To charge a customer using 2DS, add the authOptionflag in your payment method request and set it tonoauth 
{
    "reference": "193246191",
    "paymentoption": "C",
    "country": "GB",
    "card": {
        "cardnumber": "5555555555554444",
        "expirymonth": "12",
        "expiryyear": "27",
        "cvv": "123",
        "authOption": "NOAUTH",
       "billingAddress": {
            "street": "58 Blatchington Rd",
            "city": "Hove",
            "country": "GB",
            "state": "East Sussex",
            "zipCode": "BN3 3YH"
        }
    }
}