Payments API

Process payments, manage payment methods, register funding sources, and handle 3D Secure authentication flows.

Base:/api/payment, /v1/FundingSource

Endpoints

POST

/api/payment/payinvoice

Pay Invoice

Process a payment against an invoice. Supports credit/debit card, bank transfer, account balance, and wallet payment methods.

Request Body

{
  "invoiceId": 100,
  "invoiceIdentifier": "INV-2024-001",
  "paymentOptionId": 1,
  "fundingSourceId": 5,
  "card": {
    "name": "John Doe",
    "cardNumber": "4111111111111111",
    "expiryDate": "12/26",
    "cvv": "123"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "city": "Kingston",
    "country": "JM"
  },
  "sessionToken": "optional-session-token"
}

Response

{
  "referenceNumber": "PAY-20240315-001",
  "clientReferenceNumber": "CR-001",
  "invoiceIdentifier": "INV-2024-001",
  "amountPaid": 150.00,
  "amountDue": 0,
  "feePaid": 2.50,
  "currency": "USD",
  "paymentStatusId": "Success",
  "paymentDateTime": "2024-03-15T10:30:00Z",
  "paymentMethod": "CreditCard",
  "isSuccess": true,
  "approvalAction": "None",
  "authorizationCode": "AUTH123",
  "hostMessage": "Approved"
}

isSuccess is true when paymentStatusId is "Success" or "CustomerAuthRequired". For 3D Secure, check approvalAction for "Redirect" and use approvalDataOrUrl.

GET

/v1/FundingSource

Get Funding Sources

Retrieve all registered funding sources (saved payment methods) for the authenticated user.

Response

{
  "value": [
    {
      "id": 5,
      "name": "My Visa Card",
      "paymentOptionId": 1,
      "statusId": "Active",
      "isVerified": true,
      "maskedAccountNumber": "****1111",
      "expiryDate": "12/26"
    }
  ]
}

POST

/v1/payment/RegisterCard

Request Body

{
  "card": {
    "name": "John Doe",
    "cardNumber": "4111111111111111",
    "expiryDate": "12/26",
    "cvv": "123"
  },
  "name": "My Visa Card",
  "fundingSourceId": null
}

Response

{
  "message": "Card registered successfully",
  "status": "Success",
  "fundingSourceId": 5,
  "paymentResponse": {
    "isSuccess": true,
    "paymentStatusId": "Success"
  }
}

POST

/v1/fundingSource/{id}/verify

Verify Card

Verify a registered card using a verification code (micro-deposit or other verification method).

Path Parameters

Name	Type	Required	Description
id	number	Required	Funding source ID

Request Body

{
  "VerificationCode": "1234"
}

GET

/v1/invoice/{id}/PaymentMethods

Get Payment Methods

Retrieve available payment methods for a specific invoice.

Path Parameters

Name	Type	Required	Description
id	number	Required	Invoice ID

Response

{
  "value": [
    {
      "id": 1,
      "code": "VISA",
      "name": "Visa Credit Card",
      "paymentMethodId": "CreditCard",
      "paymentProviderTypeId": "Gateway",
      "paymentChannel": "Online",
      "isEnabled": true,
      "isVerificationRequired": false,
      "currencyCode": "USD"
    },
    {
      "id": 2,
      "code": "WALLET",
      "name": "QuickPay Wallet",
      "paymentMethodId": "QuickPayWallet",
      "paymentProviderTypeId": "Internal",
      "isEnabled": true
    }
  ]
}

Enums

PaymentMethod

CreditCard

DebitCard

BankTransfer

AccountBalance

QuickPayWallet

MPGS

Paypal

JamDex

PaymentChannel

Online

POS

Mobile

InApp

PaymentProviderType

Internal

External

Gateway

ApprovalAction

None

Redirect

FormData

QrCode

Types

PaymentInvoiceRequest

interface PaymentInvoiceRequest {
  invoiceId?: number;
  invoiceIdentifier?: string;
  sessionToken?: string;
  paymentOptionId: number;          // Required — payment method ID
  fundingSourceId?: number;         // Saved card/source
  sourceAccountId?: number;         // Wallet account
  card?: CardInfo;                  // New card details
  billingAddress?: CounterPartyInfoDto;
  originalPaymentReference?: string; // For refunds
}

PaymentResponse

interface PaymentResponse {
  referenceNumber?: string;
  clientReferenceNumber?: string;
  invoiceIdentifier?: string;
  amountPaid?: number;
  amountDue?: number;
  feePaid?: number;
  currency?: string;
  paymentStatusId?: string;         // "Success" | "CustomerAuthRequired" | "Failed" ...
  paymentDateTime?: string;
  paymentMethod?: string;
  isSuccess: boolean;               // true if Success or CustomerAuthRequired
  approvalAction?: 'None' | 'Redirect' | 'FormData' | 'QrCode';
  approvalDataOrUrl?: string;       // Redirect URL for 3DS
  is3DSecureAuth?: boolean;
  authorizationCode?: string;
  hostMessage?: string;
}

Usage Examples

Pay an invoice with a saved card

TypeScript

import { paymentApi } from '@/lib/api/ecommerce-client';

const response = await paymentApi.payInvoice({
  invoiceIdentifier: 'INV-2024-001',
  paymentOptionId: 1,
  fundingSourceId: 5,  // Saved card
});

if (response.isSuccess) {
  if (response.approvalAction === 'Redirect') {
    // 3D Secure — redirect user
    window.location.href = response.approvalDataOrUrl!;
  } else {
    toast.success(`Payment ${response.referenceNumber} completed`);
  }
}

TypeScript

import { paymentApi } from '@/lib/api/ecommerce-client';

// Step 1: Register card
const result = await paymentApi.registerCard({
  card: {
    name: 'John Doe',
    cardNumber: '4111111111111111',
    expiryDate: '12/26',
    cvv: '123',
  },
  name: 'My Visa',
});

// Step 2: Verify if needed
if (result.fundingSourceId) {
  await paymentApi.verifyCard(result.fundingSourceId, '1234');
}