Card Payments API
Collect local and international payments from your customer's debit/credit cards seamlessly.
Before you continue, we recommend that you read the payment overview first to understand some of our payment basics. This guide assumes that you have read our overview
The card charge API makes it easy to collect payments from local and international cards (debit and credit cards). You may charge your consumers in more than 25 different currencies, including NGN, USD, and EUR, with our card payments APIs. The card charging process involves three phases: Initiation, Authorization, and Payment confirmation. Here's an overview of the overall charge flow:
Step 1: Encrypting your Order details
To initiate a payment, you must first create an order. An order is a collection of your customer's information (customer's name, mobile number, country, and email) and transaction information (transaction amount, currency, and a reference). After collecting the required information, you'll need to encrypt your request.
//Unencrypted request
{
"customer":{
"first_name":"Example",
"last_name":"User",
"mobile":"+2348101234544",
"country":"NG",
"email":"[email protected]"
},
"order":{
"amount":100,
"reference":"Example-Reference-0020",
"description":"Test Payment",
"currency":"NGN"
},
"payment":{
"redirect_url":"https://my-company.com/success"
}
}
On successfully encrypting the transaction details, You'll receive an encrypted string.
"RYa9nWa+TnZ2O8b7HC8ru3TuIZ/FpzCKuSur7MyAH3rVIyaAqOIhY5/vBlVSNHh3WN2B2XMTiEGj4QuViqlx7TgzWiEyIq6WGKT9Jzd0XPoVrSEmLVuh4EZMPDJPXEiPnZsoEpQdFxxUlf03/OK1KcjG414Yq2s5hSA869pVZY4cz/XJ6DmttO+WX5daWoH0jlb879EN+ig4tQY3nvi2rjaF6dre2L+o3/Duh632cqX3SSCawFgNGwU/OkAim+8tFnLwC3LMpN3CjV0tMJBA4p2UyWtnNvlCNoHo55toVHjO+OIes2HwPKWOcfJjuupjuiI2zGIpFF2ywboYT+nChrxJ00sPJVizLKRsvYZ+Tqmd1QShsaNTsgBgxABUUow3CXumsLs5g+4VnhxB8lNpl8bRACb7zdu1H9fFeqWnzLhzQu5rb3c1ko/lpOXpRJl7oyYpFThTBMvtucG5ADhPyUZunnf8NevgXbfdLwi8O8BQBpgrxiqKJeDzflpIiGa4rwf3qEl4J1i7f+IzFXiVi98JRFSaaUGTS78s+Z3FOjhk1ybZ2DtgVJ4sclAr1GqbycZTPFJn9ymICbc1XCeQEFc0Mt8Z/lhm3j4cUT8Ihsi8X14fgC+Bd45HdBdWR94KPZOP1WM6QMze4bygra1qfpygff1F+5aAb1KjQ5+0rOE="
Step 2: Initiating the payment
After encrypting the order details, make a request to the create order endpoint using the encrypted data to create the payment. The transaction will have an "initiated" status and will retain this status until the payment is authorized.
Once this step is completed, you will receive a response containing important information that you need to authorize the payment. The full response contains:
- Information on the payment created like the order reference, transaction amount and transaction fees.
- The information of the merchant initiating the payment.
- The list of payment methods available to complete the payment. For each method, the name, code and supported currency are returned.
{
"data": "mEIe7ffxcgCT23dKQwHaXWOhYNX7mA/SjweOMGGFbBZLhhkAd3Ey4KG9nvh7HXFldiwmIshsgXyXctiF0DJIxkuJbE5zEPbXq3ptND3x5iX/dxVBJ8JiXXsgmsecgsQvCVWmSUd4VwYjpWv5c29hg3gl1PVGXOhX7VoeqYFuQsAEPhQlS4FZRwSLLala4EbLUf32f2IqBRMhcc4FxfetX5fwBbaoA4UxGe7huQJOkHjhkDc9WbWaYevveIoG2WlCJ0C/dEdNAcG/CLylA86SFZ/POLUx698uOJY7w35jZDpJIompT63zXi2xWDy3H7S34afNszHtnongkNrJjzxA9Y4H9HBXbjq6wqVnHdCX4NTHNUkP6CvvT2h8O1xd51DqniLFncQxlUZH7Xtyi85dcSXFkPKK6/QuzhPXYaUZBFxsrolziXnjrxmMzRH095U3P31KCfYuYOD5bkKxDVLy6b5NZ7EH7IzIdZsG7uqTd6kWoTdrKr/UnDTQCEu3DV6Xtt31easzSasA41lc7ADT5b2Q4EUltjkLZI+BUaYnd5SrRwDSuFVZe+S/AQUSMzqmps3ooWeizIVoskFvWXMaWhGVRzb/26zUmNMFYRVTWc0uPGtQ9w+G7clUpFE2MtkxLchFoi1wrF4+ey5HLxWhG8dHrvTSGsArd5c4THKKVh0="
}
{
"data": {
"order": {
"reference": "Example-Reference-001",
"processor_reference": "ARCAORD-EFF135C2-35B4-4109-ADD5-C0D2D81A251D",
"order_payment_reference": "",
"amount": 100.00,
"fee": 0.00,
"fee_rate": 0.0000,
"status_id": 1,
"status": "Initiated",
"currency": "NGN",
"narration": "Pay"
},
"subsidiary": {
"id": 0,
"name": "Busting Bubbles",
"country": "NG",
"support_email": "[email protected]",
"customization": [
{
"key": "Subsidiary_6_logo_90452416.png",
"value": "logo"
}
]
},
"customer": {
"email": "[email protected]",
"first_name": "Test",
"last_name": "User",
"mobile": "+2348101234544",
"country": "NG"
},
"payment": null,
"other_payment_options": [
{
"code": "C",
"name": "Card Payment",
"currency": "NGN"
},
{
"code": "BA",
"name": "Bank Account",
"currency": "NGN"
},
{
"code": "USSD",
"name": "USSD",
"currency": "NGN"
},
{
"code": "BANK-TRANSFER",
"name": "Pay With Bank Transfer",
"currency": "NGN"
},
{
"code": "NQR",
"name": "QR Code Payment",
"currency": "NGN"
}
],
"saved_cards": [],
"subsidiary_order_summary": {
"order_name": "Busting Bubbles Order ORDfg66038716952",
"total_amount": 100.0,
"reference": "Example-Reference-001",
"currency": "NGN",
"order_items": [
{
"name": "Summary",
"amount": 100.0
}
]
}
},
"status": "success",
"message": "Created order successfully"
}
Step 3: Charge your Customer's Card
To proceed with the payment, please add your customer's card information to the created order. Collect the card details (card number, expiry date, and CVV) along with the order reference, which is returned as data.order.reference in the initiate payment response, and encrypt the request.
// Encryption algorithm: RSA(https://arca-payment-gateway.readme.io/docs/encrypting-api-requests)
{
"reference":"Example-Reference-0021",
"payment_option":"C",
"country":"NG",
"card":{
"cvv":"291",
"card_number":"5123450000000008",
"expiry_month":"01",
"expiry_year":"39"
}
}
Charging cards using noauth
Noauth is a card authentication model that allows you to charge customers without using a 3DS challenge. To charge cards with noauth, add
auth_optionto your card encryption request.
// Encryption algorithm: RSA(https://arca-payment-gateway.readme.io/docs/encrypting-api-requests)
{
"reference":"Example-Reference-0020",
"payment_option":"C",
"country":"NG",
"card":{
"cvv":"291",
"card_number":"5123450000000008",
"expiry_month":"01",
"expiry_year":"39",
"auth_option": "noauth"
}
}
{
"data": "mEIe7ffxcgCT23dKQwHaXWOhYNX7mA/SjweOMGGFbBZLhhkAd3Ey4KG9nvh7HXFldiwmIshsgXyXctiF0DJIxkuJbE5zEPbXq3ptND3x5iX/dxVBJ8JiXXsgmsecgsQvCVWmSUd4VwYjpWv5c29hg3gl1PVGXOhX7VoeqYFuQsAEPhQlS4FZRwSLLala4EbLUf32f2IqBRMhcc4FxfetX5fwBbaoA4UxGe7huQJOkHjhkDc9WbWaYevveIoG2WlCJ0C/dEdNAcG/CLylA86SFZ/POLUx698uOJY7w35jZDpJIompT63zXi2xWDy3H7S34afNszHtnongkNrJjzxA9Y4H9HBXbjq6wqVnHdCX4NTHNUkP6CvvT2h8O1xd51DqniLFncQxlUZH7Xtyi85dcSXFkPKK6/QuzhPXYaUZBFxsrolziXnjrxmMzRH095U3P31KCfYuYOD5bkKxDVLy6b5NZ7EH7IzIdZsG7uqTd6kWoTdrKr/UnDTQCEu3DV6Xtt31easzSasA41lc7ADT5b2Q4EUltjkLZI+BUaYnd5SrRwDSuFVZe+S/AQUSMzqmps3ooWeizIVoskFvWXMaWhGVRzb/26zUmNMFYRVTWc0uPGtQ9w+G7clUpFE2MtkxLchFoi1wrF4+ey5HLxWhG8dHrvTSGsArd5c4THKKVh0=",
"message": "This endpoint is not available on production. It's available on staging for quick testing purposes"
}
After successfully encrypting your request, send the encrypted request to the pay order endpoint. This action initiates the payment processing, and immediately after, we update the transaction status to "pending-authentication". You will receive information on how your customer can authorize the payment in the response.
{
"data": {
"payment_detail": {
"redirect_url": "https://core.arcapg.com/arca-mp/api/v2/inith?mtx=ARCDTQ08756197631692183495288",
"recipient_account": null,
"payment_reference": "CPD9E44FC6-EFD3-4377-B517-561A739961DE"
},
"bank_transfer_details": null,
"order_payment": {
"order_id": 28,
"order_payment_reference": "ARCA-RANREF-0726E57A-AD59-4733-9825-F97EEC393EA2",
"currency": "NGN",
"status_id": 1,
"order_payment_response_code": "01",
"order_payment_response_message": "pending-authenticaion",
"order_payment_instrument": null,
"remarks": "Order payment initiated",
"total_amount": 114.00,
"fee": 14.00
}
},
"status": "success",
"message": "Card order created successfully"
}
Step 4: Authorize the Payment
Once the charge is processed, customers are redirected to their bank's page, where they input their token or transaction pins to complete the payment. The banks handle this authorization directly and then return the user to Arca after the payment is completed. For a seamless experience, you need to ensure proper redirection and set up callbacks (or redirect URLs) in your app. This allows for graceful routing back and forth, ensuring smooth transitions during the authorization.
Transaction redirect
After completing your payment, Arca redirects the customer to the URL you provide i.e.
redirect_url. We append the order reference and response to the URL on redirect.
//redirect_url structure
https://my-company.com/process_complete?order_payment_reference={{order_payment_reference}}&status={{order_status}}
//sample
https://my-company.com/process_complete?order_payment_reference=ARCPAY-6BBBBBB2CFDF460AAA411111&status=successful
Step 5: Verify the Payment
Great news! You have completed the payment. However, before delivering value or providing service, it is important to confirm the payment's success. To do this, pass the order_reference to the verify endpoint to check and confirm its final status. This will ensure that the payment was indeed successful before closing the transaction.
{
"data":{
"order_reference":"SDPASV33624842",
"payment_reference":"ARCAORD-B6D9259227EA11EFBDBC0AD371968847",
"product_name":"Collection",
"total_amount_charged":10.0000,
"status_id":5,
"status":"Successful",
"payment_method":"Card Payment",
"payment_response_code":"00",
"payment_response_message":"Successful",
"narration":"Pay",
"remarks":"Order initiated and created successfully",
"currency_id":6,
"currency_name":"USD",
"fee":0.0000,
"fee_rate":0.0000,
"subsidiary_fee":0.0000,
"customer_fee":0.0000,
"date_created":"2024-06-11T12:04:11",
"date_updated":"2024-06-11T12:04:44.30046",
"date_payment_confirmed":null,
"order_payments":[
{
"order_id":150820,
"order_payment_reference":"ARCPAY-F511F47444BC4F9B916F3951834D57F0",
"payment_option_id":2,
"payment_option":"Card Payment",
"status_id":5,
"status":"Successful",
"response_code":"00",
"response_message":"Successful",
"order_payment_instrument":null,
"remarks":"Order payment updated",
"date_created":"2024-06-11T12:04:13.193647",
"date_updated":"2024-06-11T12:04:44.300503"
}
],
"customer":{
"customer_id":"[email protected]",
"first_name":"lll",
"last_name":"mla",
"email_address":"[email protected]",
"country_short_name":"NG",
"customer_group":"Default",
"country_id":1,
"global_status_id":2,
"global_status":"Active",
"mobile_number":"+2348101234542",
"is_blacklisted":false,
"reason_blacklisted":null,
"date_created":"2024-06-05T21:45:28",
"date_updated":null
},
"card_details":[
{
"order_payment_id":150723,
"status":true,
"country":"NG",
"card_token":"UFYzeGra16AvMxVzvRI8HDqZqiNQiywWKKypMsDryQA=",
"card_expiry_month":"01",
"card_expiry_year":"39",
"card_type":null,
"card_issuer":null,
"card_first_six_digits":"512345",
"card_last_four_digits":"0008",
"date_created":"2024-06-11T12:04:44.304815",
"app_environment_id":1
}
]
},
"status":"success",
"status_code":"00",
"message":"Orders fetched successfully"
}
Updated 3 months ago