Guides

Payment APIs

Collect payments online from your Customers with ARCA APIs

Suggest Edits

Arca Payment APIs provide a robust payment experience for merchants looking to accept payment.

Use cases

The Payment API provides the essential components that power our checkout solution. You can use these components any way you choose to develop solutions that meet your business needs. Some examples of how our payment APIs can be used include:

  1. Creating a custom payment experience: As a merchant, you may desire a unique payment flow in your application for your users. The payment APIs enable you to create branded UI screens, dedicated UX features like saving cards or implementing a "remember me" option and help you to better manage the payments in your application.
  2. Developing offline solutions: If you are developing offline solutions or seeking to incorporate an offline mode into your app, our APIs offer the necessary functionality. By batching API calls, you can initiate payments from your servers and then notify users (via their mobile numbers) to complete the transactions.
  3. Creating an Enterprise Solution: Our payment APIs seamlessly integrate with your enterprise management tools and ERPs. This integration streamlines payment management for your business, allowing you to efficiently combine it with other related operations like inventory management.

Integration Requirements

Before you continue, Please read our getting started guide to create your account, set up your webhooks and get your API keys for the integration. If you have done this, you can proceed with your integration.

How our Integration works

In this section, We outline the necessary steps for implementing your integration

  1. From your server, encrypt your transaction details (including customer's data) and send your request to initiate the payment.
  2. Create a form on your app or website to gather your customer's payment information, such as card details and other information to identify the customer.
  3. Send the customer's payment information securely to your preferred payment method endpoint.
  4. In some scenarios, you may need to redirect your customer to their bank's page or another designated page for further processing.
  5. On your server, query the final status of the transaction to ensure its completion successfully.

Various payment methods entail additional nuances, and the specific steps involved will differ for each method. Below, we provide further information on integrating each payment method:

  1. Cards
  2. Pay with Bank Transfer
  3. Pay with Bank account (coming soon).
  4. USSD (coming soon).
  5. Pay with NQR (coming soon).

Authorizing your requests

To successfully make calls to all the endpoints mentioned in this document, you need to include your API keys in the request headers. You can access these keys in the settings section of your dashboard. Here is a walkthrough guide on how to fetch your keys.

  1. log into your dashboard
  2. Select settings from your side menu.
  3. Click on "API keys and Webhooks" option in the sub menu to reveal your keys.
  4. Copy your keys from the dashboard. Your keys are unique to your account and should be handled discreetly.

Testing your Integrations

To assist you in testing your integrations, we offer mock credentials. These credentials enable you to simulate both successful and failed scenarios. Below are some test cards you can utilize for your tests:

Mastercard Success Mock Card
CVV: 100
Card Number: 5123450000000008
Expiry Month:01
Expiry Year: 39

Visa Success Mock Card
CVV: 100
Card Number: 4508750015741019
Expiry Month:01
Expiry Year: 39

Visa Success Mock Card 2
CVV: 111
Card Number: 4000000000002503
Expiry Month:03
Expiry Year: 50

Verve Success Mock Card
CVV: 111
Card Number: 5060990580000217499
Expiry Month:03
Expiry Year: 50
Pin: 1111
OTP: 123456

Verve Failed Mock Card
CVV: 111
Card Number: 5060990580000000390
Expiry Month:03
Expiry Year: 50
Pin: 1111
OTP: 123456

Webhooks

Webhooks play a vital role in your integration, as they facilitate timely notifications about events related to your payments. You should consider using webhooks for asynchronous actions in your app. These actions include:

  1. Completing an offline USSD payment.
  2. Finalizing a Bank Transfer via a Bank app or an Internet banking platform.
  3. A customer making a recurring payment (for subscriptions).

With webhooks, you can stay informed about these important events throughout your payment flow.

Setting up your Webhooks

To activate webhooks on your account, please follow these steps:

  1. Sign in to your Arca account.
  2. Go to the settings and choose the "API keys and Webhooks" submenu.
  3. Add your webhook URL to the webhook URL section.
  4. Click the "Add URL" button to confirm the setup.

Here is a sample webhook response for a successful card transaction.

{
   "data":{
      "orderReference":"LOADTEST14584044",
      "paymentReference":"ARCAORD-1EAC2D3723E611EFBDBC0AD371968847",
      "productName":"Collection",
      "totalAmountCharged":8.0000,
      "statusId":5,
      "status":"Successful",
      "paymentMethod":"Card Payment",
      "paymentResponseCode":"00",
      "paymentResponseMessage":"Successful",
      "narration":"Load Test Payment",
      "remarks":"Order initiated and created successfully",
      "currencyId":1,
      "currencyName":"NGN",
      "fee":0.0000,
      "feeRate":0.0000,
      "subsidiaryFee":0.0000,
      "customerFee":0.0000,
      "dateCreated":"2024-06-06T09:21:13",
      "dateUpdated":"2024-06-06T09:21:29.291889",
      "datePaymentConfirmed":null,
      "orderPayments":[
         {
            "orderId":10257,
            "orderPaymentReference":"ARCPAY-4FDCCD960D44464B89D34A831C8EEFC1",
            "paymentOptionId":2,
            "paymentOption":"Card Payment",
            "statusId":5,
            "status":"Successful",
            "responseCode":"00",
            "responseMessage":"Successful",
            "orderPaymentInstrument":null,
            "remarks":"Order payment initiated",
            "dateCreated":"2024-06-06T09:21:26.084735",
            "dateUpdated":"2024-06-06T09:21:29.291915"
         }
      ],
      "customer":{
         "customerId":"[email protected]",
         "firstName":"lll",
         "lastName":"mla",
         "emailAddress":"[email protected]",
         "countryShortName":"NG",
         "customerGroup":"Default",
         "countryId":1,
         "globalStatusId":2,
         "globalStatus":"Active",
         "mobileNumber":"\u002B2348101234542",
         "isBlacklisted":false,
         "reasonBlacklisted":null,
         "dateCreated":"2024-06-05T22:15:54",
         "dateUpdated":null
      },
      "cardDetails":[
         {
            "orderPaymentId":10259,
            "status":true,
            "country":"NG",
            "cardToken":"FqBK2gPJu0FiWIyOTTjD61qDS3pTBxuUWv5E9h1Hz20=",
            "cardExpiryMonth":"03",
            "cardExpiryYear":"26",
            "cardType":null,
            "cardIssuer":null,
            "cardFirstSixDigits":"418745",
            "cardLastFourDigits":"7988",
            "dateCreated":"2024-06-06T09:21:29.296528",
            "appEnvironmentId":2
         }
      ]
   },
   "status":"success",
   "statusCode":"00",
   "message":"Orders fetched successfully"
}

Updated 5 months ago

What’s Next