Card Payments

Card Payments API

Process Visa, Mastercard, and Amex payments with 3DS2 security via DPO.

3DS2 Verification

Card payments may require 3DS2 verification. When a paymentUrl is returned, redirect the customer to complete verification. They'll be redirected back to yourredirectUrl after completion.

Supported Card Networks

Visa, Mastercard, American Express • PCI DSS Compliant • 3DS2 Secure

POST/api/v1/payments/charge

API Key Required

Charge Card

Process a card payment. Returns a payment URL for 3DS verification if required.

Parameter	Type	Description
`amount`required	`number`	Amount to charge Example: `100.00`
`currency`required	`string`	3-letter ISO currency code Example: `USD`
`reference`required	`string`	Your unique order reference (1-50 chars) Example: `ORDER-001`
`description`	`string`	Payment description Example: `Order payment`
`customer.email`required	`string`	Customer email address Example: `john@example.com`
`customer.firstName`required	`string`	Customer first name Example: `John`
`customer.lastName`required	`string`	Customer last name Example: `Doe`
`customer.phone`	`string`	Customer phone number Example: `+254712345678`
`card.number`required	`string`	Card number (no spaces) Example: `4242424242424242`
`card.expiry`required	`string`	Card expiry in MM/YY format Example: `12/26`
`card.cvv`required	`string`	Card CVV (3-4 digits) Example: `123`
`card.holderName`required	`string`	Name on card Example: `John Doe`
`callbackUrl`required	`string`	URL for payment notification Example: `https://your-site.com/webhook`
`redirectUrl`	`string`	URL to redirect after 3DS Example: `https://your-site.com/complete`

Code Examples

const response = await fetch('https://api.serixpay.com/api/v1/payments/charge', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_test_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100.00,
    currency: 'USD',
    reference: 'ORDER-001',
    description: 'Order payment',
    customer: {
      email: 'john@example.com',
      firstName: 'John',
      lastName: 'Doe',
      phone: '+254712345678'
    },
    card: {
      number: '4242424242424242',
      expiry: '12/26',
      cvv: '123',
      holderName: 'John Doe'
    },
    callbackUrl: 'https://your-site.com/webhook',
    redirectUrl: 'https://your-site.com/complete'
  })
});

const data = await response.json();

// Redirect customer to 3DS page if needed
if (data.paymentUrl) {
  window.location.href = data.paymentUrl;
}

GET/api/v1/payments/:id

Get Transaction

Retrieve details of a card transaction by its ID.

{
  "success": true,
  "transaction": {
    "id": "txn_abc123xyz",
    "reference": "ORDER-001",
    "amount": 100.00,
    "currency": "USD",
    "status": "completed",
    "customer": {
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "card": {
      "last4": "4242",
      "brand": "visa",
      "expiryMonth": "12",
      "expiryYear": "26"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:30:45Z"
  }
}

POST/api/v1/payments/:id/refund

API Key Required

Refund Payment

Process a full or partial refund for a completed transaction.

Parameter Type Description

Parameter	Type	Description
`amount`required	`number`	Amount to refund (must be <= original amount) Example: `50.00`
`reason`required	`string`	Reason for refund (1-200 chars) Example: `Customer requested refund`
`reference`	`string`	Your refund reference Example: `REFUND-001`

amountrequired

number

Amount to refund (must be <= original amount)

Example: 50.00

reasonrequired

string

Reason for refund (1-200 chars)

Example: Customer requested refund

reference

string

Your refund reference

Example: REFUND-001

Code Examples

const transactionId = 'txn_abc123xyz';

const response = await fetch(
  `https://api.serixpay.com/api/v1/payments/${transactionId}/refund`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_test_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 50.00,
      reason: 'Customer requested refund',
      reference: 'REFUND-001'
    })
  }
);

const data = await response.json();
console.log(data.refundId);

Test Cards

Use these test card numbers in sandbox mode:

Card Number	Brand	Result
4242 4242 4242 4242	Visa	Success
5555 5555 5555 4444	Mastercard	Success
4000 0000 0000 0002	Visa	Declined
4000 0000 0000 9995	Visa	Insufficient Funds

Use any future expiry date and any 3-digit CVV for test cards.

Transaction Statuses

pendingPayment initiated, awaiting 3DS

processingPayment being processed

completedPayment successful

failedPayment declined

refundedFully refunded

partially_refundedPartially refunded