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:
- The merchant collects the customer's card details and assigns an order reference for the payment.
- Alliance Pay checks the transaction request and processes the payment.
- Where 3DS is
- Required, the customer is redirected to their bank's page for authentication.
- Not required, because
authOption
is set tonoauth
, 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:
- Create a request with the card information. This should include the card number, expiry date and CVV.
- Encrypt your request containing the customer's card information. We covered encryption in detail here.
- Send your request to the pay order endpoint.
- Redirect your customers to
payment_detail.redirect_url
to 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 authOption
flag 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:
- A customer saving their card information for quicker checkout on retail and e-commerce websites.
- 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:
- Including the
saveCard
feature in your pay order request. This works well when the customer is available to complete the charge. - 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
saveCard
flagTo save a customer's card after the charge, include the saveCard
flag 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:
-
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" }
-
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" } }
-
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" }
Updated 1 day ago