Libraries and SDKsNode.jsPayment Services

Payment Services

The Payment Services module allows you to process payments through multiple channels, including checkout pages, direct card charges, bank transfers, and mobile money.

Available Payment Services

Checkout

The Checkout service provides a hosted payment page that you can redirect your customers to.

Initialize Payment Checkout

Creates a payment checkout session and returns a URL for the customer to complete the payment.

const checkoutResponse = await client.payment.checkout.initialize({
  first_name: "John",
  last_name: "Doe",
  email: "johndoe@gmail.com",
  amount: "100",
  currency: "NGN",
  reference: client.generateReference(),
  redirectUrl: "https://yourwebsite.com/callback",
  title: "Payment for Order",
  description: "Order #12345",
  logoUrl: "https://yourwebsite.com/logo.png"
});
 
// Redirect the customer to the checkout URL
console.log('Checkout URL:', checkoutResponse.data.checkout_url);

Parameters

ParameterTypeRequiredDescription
first_namestringYesCustomer’s first name
last_namestringYesCustomer’s last name
emailstringYesCustomer’s email address
amountstringYesPayment amount
currencystringYesPayment currency (e.g., NGN)
referencestringYesUnique transaction reference
redirectUrlstringYesCallback URL after payment
titlestringYesPayment title
descriptionstringYesPayment description
logoUrlstringNoURL of your logo

Response

{
  status: "success",
  message: "Checkout initialized successfully",
  data: {
    checkout_url: "https://checkout.cashonrails.com/pay/abcdef12345",
    transaction_reference: "COR_1234567890",
    amount: "100",
    currency: "NGN"
  }
}

Verify Transaction

After a customer completes payment, you should verify the transaction status:

const verificationResponse = await client.payment.checkout.verify('transaction_reference');
 
if (verificationResponse.data.status === 'successful') {
  // Process order fulfillment
  console.log('Payment successful!');
} else {
  // Handle failed payment
  console.log('Payment failed:', verificationResponse.data.status);
}

Parameters

ParameterTypeRequiredDescription
transaction_referencestringYesReference of the transaction to verify

Response

{
  status: "success",
  message: "Transaction verified",
  data: {
    reference: "COR_1234567890",
    amount: "100",
    currency: "NGN",
    status: "successful", // or "failed", "pending"
    payment_method: "card",
    paid_at: "2023-05-15T10:30:00Z",
    customer: {
      email: "johndoe@gmail.com",
      name: "John Doe"
    }
  }
}

Direct Charge

The Direct Charge service allows you to process payments directly without redirecting customers to a hosted page.

Card Payments

Process a payment directly using card details:

const cardPayment = await client.payment.directCharge.card({
  email: "test@example.com",
  amount: "100",
  currency: "NGN",
  card: {
    number: "4111111111111111",
    cvv: "123",
    expiryMonth: "12",
    expiryYear: "25",
    pin: "1234"
  }
});
 
console.log('Card Payment Response:', cardPayment);

Parameters

ParameterTypeRequiredDescription
emailstringYesCustomer’s email address
amountstringYesPayment amount
currencystringYesPayment currency (e.g., NGN)
card.numberstringYesCard number
card.cvvstringYesCard CVV
card.expiryMonthstringYesCard expiry month (MM)
card.expiryYearstringYesCard expiry year (YY)
card.pinstringYesCard PIN

Bank Transfers

Initialize a direct bank transfer:

const bankTransfer = await client.payment.directCharge.initBankTransfer({
  account_number: "1234567890",
  bank_code: "000013",
  amount: "5000",
  currency: "NGN",
  email: "johndoe@gmail.com",
  reference: client.generateReference()
});
 
console.log('Bank Transfer Response:', bankTransfer);

Parameters

ParameterTypeRequiredDescription
account_numberstringYesCustomer’s account number
bank_codestringYesBank code
amountstringYesTransfer amount
currencystringYesTransfer currency
emailstringYesCustomer’s email
referencestringYesUnique reference

Mobile Money

Process a payment using mobile money services:

const mobileMoneyPayment = await client.payment.directCharge.chargeWithPhone({
  phone_number: "08012345678",
  provider: "mtn",
  amount: "2000",
  currency: "NGN",
  email: "johndoe@gmail.com",
  reference: client.generateReference()
});
 
console.log('Mobile Money Payment Response:', mobileMoneyPayment);

Parameters

ParameterTypeRequiredDescription
phone_numberstringYesCustomer’s phone number
providerstringYesMobile money provider (e.g., mtn)
amountstringYesPayment amount
currencystringYesPayment currency
emailstringYesCustomer’s email
referencestringYesUnique reference

List Available Banks

Retrieve a list of available banks for payment processing:

const banks = await client.payment.directCharge.listAvailableBanks();
console.log('Available Banks:', banks.data);

Response

{
  status: "success",
  message: "Banks retrieved successfully",
  data: [
    {
      code: "000013",
      name: "First Bank of Nigeria"
    },
    {
      code: "000014",
      name: "Guaranty Trust Bank"
    },
    // More banks...
  ]
}

Best Practices for Payments

  1. Always verify transactions after completion
  2. Generate unique references for each transaction
  3. Store transaction references in your database
  4. Handle failed payments gracefully
  5. Implement proper error handling for all payment operations
  6. Use webhooks for asynchronous payment notifications

Error Handling for Payments

try {
  const checkout = await client.payment.checkout.initialize({
    // Payment details
  });
  
  // Process successful checkout
  console.log('Checkout URL:', checkout.data.checkout_url);
} catch (error) {
  // Handle payment errors
  console.error('Payment initialization failed:', error.message);
  
  if (error.code === 'INVALID_AMOUNT') {
    console.error('Invalid payment amount');
  } else if (error.code === 'CURRENCY_NOT_SUPPORTED') {
    console.error('Currency not supported');
  }
}

For more details on error handling, see the Error Handling documentation.

Related Resources

Client ConfigurationTransfers