Card Payments

Cards are an incredible way of collecting payment from your customers. You can receive payments from Mastercard, Visa and Verve cards.


Authentication models

Authentication models are used for payment authentication i.e. confirming that a cardholder is actually performing a transaction. These help to prevent fraudulent transactions and build trust with your customers.

Alliance Pay processes card payments using 3DS auth model. With 3DS, the customer is redirected to an authentication page to input a code or password sent to their phone.

In a typical payment flow that utilizes 3DS:

  1. The merchant collects the customer's card details and assigns an order reference for the payment.
  2. Alliance Pay checks the transaction request and processes the payment.
  3. Where 3DS is
    1. Required, the customer is redirected to their bank's page for authentication.
    2. Not required, because authOption is set to noauth, the customer is not redirected and the payment is completed automatically. This is also called the 3DS frictionless flow.

Collecting card payments using 3DS

Follow these steps to complete payment using 3DS:

  1. Create a request with the card information. This should include the card number, expiry date and CVV.
  2. Encrypt your request containing the customer's card information. We covered encryption in detail here.
  3. Send your request to the pay order endpoint.
  4. Redirect your customers to payment_detail.redirect_urlto complete the payment.

Here are samples to guide your implementation.

//unencrypted
{
   "reference":"ORD001",
   "paymentoption":"C", //pass C as payment_option for card payments
   "country":"NG",
   "card":{
       "cvv":"101",
       "cardnumber":"5123450000000008",
       "expirymonth":"02",
       "expiryyear":"30"
   }
}
//encrypted
{
  "data": "B9pQJ1HoxybgfjNnEro+26w7lQZ6jriF3AFiUeGH2Ggacn6cF0srUlqiHEXeEncJcMw6ThDobjuS+AsmvhNfvGPGMddjbt5rcK2JrUnUI4cHk0XebJKoNnjEqivcyq0UKEMdYOLd6mYZtvKu5FMlpz0Lo0aMY49pnYvUGLSsCf/wOhlPx9PHgQDXptT+WBJcO3lzeD8O0S4IVSWPCWPLi7GhGlqhZpheEi1FHq39TCHk12hL3sqkkIktZIkkQVAe8AkwZGhy/CMJZrTzU6IXZr2ulT7mJenZljSk66m0pARcUqwMw/+5PEPECDo8SX3IkX2hmym02pGuWZeHE9ONWcaW7h8UIroQ/+kThz/RtP/UMiK3596cij66JcW+RcXKPiqNKysskcnaOlQFIFuhEiAczimLgd320RrQzehaw1C33UGsCzAG1p2EnDthjTF63BZtEhVlu9kN7qtFCz9AvojZeaZFKOxpJJ0usfwl9Hq5oAa56AFt/3IIsvqrAktTOyMgQ/jGQ6uhRYpA6UAH0CcYyv7L99hgVtRTXAxA/rpCtY7aTR9Pjxb5Lt1IV0Q1V8fWxAv0yY+ss07qeiSIsccsdJiN4LaMx3RvmDlu54XF68w51L34hOCDj/NBoPVUZrSaCJK2GPJ6CjOHI8q2/U2TkU+y+a80XCAC/rgqGhw="
}
{
  "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"
}

Collecting card payments using 2DS or 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": "NG",
    "card": {
        "cardnumber": "5123450000000008",
        "expirymonth": "01",
        "expiryyear": "39",
        "cvv": "100",
        "authOption": "NOAUTH"
    }
}
{
  "data": "B9pQJ1HoxybgfjNnEro+26w7lQZ6jriF3AFiUeGH2Ggacn6cF0srUlqiHEXeEncJcMw6ThDobjuS+AsmvhNfvGPGMddjbt5rcK2JrUnUI4cHk0XebJKoNnjEqivcyq0UKEMdYOLd6mYZtvKu5FMlpz0Lo0aMY49pnYvUGLSsCf/wOhlPx9PHgQDXptT+WBJcO3lzeD8O0S4IVSWPCWPLi7GhGlqhZpheEi1FHq39TCHk12hL3sqkkIktZIkkQVAe8AkwZGhy/CMJZrTzU6IXZr2ulT7mJenZljSk66m0pARcUqwMw/+5PEPECDo8SX3IkX2hmym02pGuWZeHE9ONWcaW7h8UIroQ/+kThz/RtP/UMiK3596cij66JcW+RcXKPiqNKysskcnaOlQFIFuhEiAczimLgd320RrQzehaw1C33UGsCzAG1p2EnDthjTF63BZtEhVlu9kN7qtFCz9AvojZeaZFKOxpJJ0usfwl9Hq5oAa56AFt/3IIsvqrAktTOyMgQ/jGQ6uhRYpA6UAH0CcYyv7L99hgVtRTXAxA/rpCtY7aTR9Pjxb5Lt1IV0Q1V8fWxAv0yY+ss07qeiSIsccsdJiN4LaMx3RvmDlu54XF68w51L34hOCDj/NBoPVUZrSaCJK2GPJ6CjOHI8q2/U2TkU+y+a80XCAC/rgqGhw="
}
{
    "data": {
        "paymentDetail": {
            "redirectUrl": null,
            "recipientAccount": null,
            "paymentReference": "CP73C65657-6E07-48DB-9D0B-722BABCAB8ED"
        },
        "bankTransferDetails": null,
        "orderPayment": {
            "orderId": 38,
            "orderPaymentReference": "PGW-PAYREF-CEF850B7CAFD4D24B054DC75BEA763BB",
            "currency": "NGN",
            "statusId": 2,
            "orderPaymentResponseCode": "00",
            "orderPaymentResponseMessage": "Transaction was completed successfully",
            "orderPaymentInstrument": null,
            "remarks": "Order payment initiated",
            "totalAmount": 212.00,
            "fee": 12.00
        }
    },
    "status": "success",
    "statusCode": "00",
    "message": "Transaction was completed successfully"
}

Using the save card feature

Sometimes, you need to save a customer's card after a transaction to make subsequent payments easier and quicker. This is very useful in scenarios where the customer needs to make multiple payments quickly.

For example:

  1. A customer saving their card information for quicker checkout on retail and e-commerce websites.
  2. Link your card to a wallet for seamless funding without re-entering card details.

There are two methods to saving your customer's card information, both equally effective, depending on your use case:

  1. Including the saveCard feature in your pay order request. This works well when the customer is available to complete the charge.
  2. Tokenizing the card information after the charge. With this method, the customer must have previously completed a charge and given consent to save their card.

Using the saveCard flag

To save a customer's card after the charge, include the saveCardflag in your pay with card request before encrypting it.

{
    "reference": "{{orderreference}}",
    "paymentoption": "C",
    "country": "NG",
    "card": {
        "cardnumber": "5123450000000008",
        "expirymonth": "01",
        "expiryyear": "39",
        "cvv": "100",
        "saveCard": true
    }
}

After encrypting the customer's card information, send the encrypted request to the pay order endpoint.

{
  "data": "B9pQJ1HoxybgfjNnEro+26w7lQZ6jriF3AFiUeGH2Ggacn6cF0srUlqiHEXeEncJcMw6ThDobjuS+AsmvhNfvGPGMddjbt5rcK2JrUnUI4cHk0XebJKoNnjEqivcyq0UKEMdYOLd6mYZtvKu5FMlpz0Lo0aMY49pnYvUGLSsCf/wOhlPx9PHgQDXptT+WBJcO3lzeD8O0S4IVSWPCWPLi7GhGlqhZpheEi1FHq39TCHk12hL3sqkkIktZIkkQVAe8AkwZGhy/CMJZrTzU6IXZr2ulT7mJenZljSk66m0pARcUqwMw/+5PEPECDo8SX3IkX2hmym02pGuWZeHE9ONWcaW7h8UIroQ/+kThz/RtP/UMiK3596cij66JcW+RcXKPiqNKysskcnaOlQFIFuhEiAczimLgd320RrQzehaw1C33UGsCzAG1p2EnDthjTF63BZtEhVlu9kN7qtFCz9AvojZeaZFKOxpJJ0usfwl9Hq5oAa56AFt/3IIsvqrAktTOyMgQ/jGQ6uhRYpA6UAH0CcYyv7L99hgVtRTXAxA/rpCtY7aTR9Pjxb5Lt1IV0Q1V8fWxAv0yY+ss07qeiSIsccsdJiN4LaMx3RvmDlu54XF68w51L34hOCDj/NBoPVUZrSaCJK2GPJ6CjOHI8q2/U2TkU+y+a80XCAC/rgqGhw="
}
{
    "data": {
        "paymentDetail": {
            "redirectUrl": "https://core-staging.staging-alliancepay.io/ap-mpgs/api/v2/starttx?txref=ALPOMQ13882583551739367344779",
            "recipientAccount": null,
            "paymentReference": "CPBC40B380-0072-40B3-971B-C286D50B555C"
        },
        "bankTransferDetails": null,
        "orderPayment": {
            "orderId": 33,
            "orderPaymentReference": "PGW-PAYREF-BFE6566B532D45AF9A7B99A1CEAE72A7",
            "currency": "NGN",
            "statusId": 2,
            "orderPaymentResponseCode": "02",
            "orderPaymentResponseMessage": "pending-authenticaion",
            "orderPaymentInstrument": null,
            "remarks": "Order payment initiated",
            "totalAmount": 212.00,
            "fee": 12.00
        }
    },
    "status": "success",
    "statusCode": "02",
    "message": "pending-authenticaion"
}

On querying the order's status, data.orderPayments.saveCard is true in the response.


Saving Card information after a charge

🚧

This method only works for previously completed payments.

To save your customer's card after a charge, encrypt the reference of the successful order and send it to the save card endpoint.

{
    "reference": "DWErSBFXJW51b#xTY_8yFJDmg2JT#zVuJxYQMkHwE1ze124-12"
}
{
    "data": "Eaob/rPZMqCjpqBewT6KSD8LyBCLrDP+pohHR2irgDb9do8iPvQNmmuZqijlwFlglfaj6hd/e/6mrWcl+ROgvrPQdWTnAcKn++qOZUE50cst9HZKD4RRYOL8BzrKygzcCGKGgGS3uoKpasJFK8BfK9LMc7zy6xP72RoiizTbwb0ZaOUwbxU5s2n7+fi2DMnmlokIkgOKWzD58sjZlrpmsRWIQF9TsIUIfUoV+yLPc6sjslLT5lMJyXtLSqxg5Zva+qr8tm2mRubHCjkYDvpepbf3I4C1HyGA44WHQ5wx6vKCi50SslmCuQTxEzTB0Hrt6ucBskHxBPHyGrZAiGtsvmrYUgCgoKOtpBUL3NvM/HMnloB+tCpHK5/0xFEnjUXsWHidYxh65SwUkv9JdeCcqBFmtGOQqHgikx2bR5A8uxDxJ/qTLbHDWv5UlO/ukHhAWqWSdTvUMsJ096Ex2zPUzAfrHMevFrzNov6cuZi2WfmbKE1FzAz6UtC46YEUlFWvapGxuK/TtstgSt3pO/o9TJyaXBPwTNdG7EjZowd8g4uQlIhi1H+RvIpfxcg6iD6lXUmKc1121iITfO/1QAbFvNYYcCqCvhnU3dYuqVC7l9cAF7Fo39o41a4pCGg6OlsUS8XxbDiuZXUgMU3z2DZ69LgkAHeZ8S2c2gJUANpVM8IYmAqK+fxWlKBFzK6ozSj4VnQxix2QSqS6RYdkDjUPeO70BzP4zvjbwNqZbSilGIPm/9Mx468ZVCnOu16jNHizEmlI1PNkke/anZauc7QDAKOIPZXzdKsnpxnGDfP8z9HZkjN4YCCVyC55pPKtPPtiXAsOiq3OgWr6rKUBM44UjkWvu/xv5n7nEIyFPsm0gMOFWzrUlF477L3bwJnxRQ6pjX7SAIB2dDq0GZ8F3CpCtA6FFDITfaO123zcqbg7XjuSx24u0rD9AAY2PyTqpHlp8p2GVh/MZ7ccRy/Lj2kUucM7Iy2/Thhpqm93Sg016bqJWqnFmxLFSZWUz5x5in5LAHKTORuEL3q8da3M074i4TTe9ReUHJLVHflWOYfr5pVMbw5NjkJ9V2DnAI144u76/4gpU6jr4LNWTt9r/Z7MJFdN4W8MzxnlmEGaeBwh0beraDoerbal07A7i1m5ecVWuISN6oaWii3Cb16/dkDtN17oiwTqdW0MijaTMBqPl3J5StWXUWMMa7Na+UPCiA2jd4MOvg4CbT6xG2AKyg/ipkZjS12EuMYnQVrcv/u8JOFdEO3zu8OHxCjyNz2b4v2ox6v96ACPikmRRjqg3yrrD5ejDfw7S/xISwfQLnM0FO5V1zl+YQVHwBenLsblZuHOb/s1urEfhaB9B0SQhmIkVA=="
}
{
    "data": null,
    "status": "success",
    "statusCode": "00",
    "message": "Card saved successfully"
}

Card token charge

Saving your customer's card information is the first step in re-using the card for future payments. The card details must be retrieved and used in subsequent charges. This process is called tokenization i.e. when the customer's card details are mapped to a string (called cardToken), and the token is used to charge the customer.

To charge a customer using their card token, follow these steps:

  1. Verify the transaction where the card was saved to retrieve the card token.

    {
        "data": {
            "orderReference": "DWErSBFXJW51b#xTY_8yFJDmg2JT#zVuJxYQMkHwE1ze124-as3",
            "paymentReference": "ALP-3B981C22E95011EF8D76024163CF7247",
            "productName": "Collection",
            "totalAmountCharged": 212.0000,
            "statusId": 2,
            "status": "Pending",
            "paymentMethod": "Card Payment",
            "paymentResponseCode": "00",
            "paymentResponseMessage": "Operation successful",
            "narration": "Pay",
            "remarks": "Order initiated and created successfully",
            "currencyId": 1,
            "paymentLinkId": null,
            "paymentLinkReference": null,
            "recurringPaymentId": null,
            "recurringPaymentReference": null,
            "currencyName": "NGN",
            "fee": 12.0000,
            "feeRate": 12.0000,
            "subsidiaryFee": 0.0000,
            "customerFee": 12.0000,
            "dateCreated": "2025-02-12T14:47:07",
            "dateUpdated": null,
            "datePaymentConfirmed": null,
            "orderPayments": [
                {
                    "orderId": 35,
                    "orderPaymentReference": "PGW-PAYREF-B3E3EC3105E64985978B685E6345E6CB",
                    "paymentOptionId": 2,
                    "paymentOption": "Card Payment",
                    "statusId": 2,
                    "status": "Pending",
                    "responseCode": "00",
                    "responseMessage": "Operation successful",
                    "orderPaymentInstrument": null,
                    "remarks": "Order payment initiated",
                    "dateCreated": "2025-02-12T14:47:07.886354",
                    "dateUpdated": "2025-02-12T14:47:08.899071"
                }
            ],
            "customer": {
                "customerId": null,
                "firstName": null,
                "lastName": null,
                "emailAddress": null,
                "countryShortName": null,
                "customerGroup": null,
                "countryId": 0,
                "globalStatusId": 0,
                "globalStatus": null,
                "mobileNumber": null,
                "isBlacklisted": false,
                "reasonBlacklisted": null,
                "dateCreated": "0001-01-01T00:00:00",
                "dateUpdated": null
            },
            "cardDetails": [],
            "paymentLink": null
        },
        "status": "success",
        "statusCode": "00",
        "message": "Order details fetched successfully"
    }
    
  2. Collect the customer, order and payment details. Include the cardToken in the authorization object of your request.

    {
        "customer": {
            "firstname": "King",
            "lastname": "James",
            "mobile": "+23481582333444",
            "country": "NG",
            "email": "james@gmail.com"
        },
        "order": {
            "amount": 200,
            "reference": "asdf;lkj",
            "description": "Pay",
            "currency": "NGN"
        },
        "payment": {
            "RedirectUrl": "https://www.google.com"
        },
        "authorization": {
            "cardToken": "TKNMzM5NjQzNzA3NjgzNjg1NzM4Njg0MDk3NzY3ODE2120"
        }
    }
    
  3. Send your request to the tokenize charge endpoint.

    {
        "data": {
            "paymentDetail": {
                "redirectUrl": null,
                "recipientAccount": null,
                "paymentReference": null
            },
            "bankTransferDetails": null,
            "orderPayment": {
                "orderId": 36,
                "orderPaymentReference": "PGW-PAYREF-311B93BF7E1E4D8F9750C65F355B28EB",
                "currency": "",
                "statusId": 2,
                "orderPaymentResponseCode": "00",
                "orderPaymentResponseMessage": "Operation successful",
                "orderPaymentInstrument": null,
                "remarks": "Order payment initiated",
                "totalAmount": 212.00,
                "fee": 12.00
            }
        },
        "status": "success",
        "statusCode": "00",
        "message": "Operation successful"
    }