Card Collection API Reference

This page documents the core endpoints used in the hosted card collection flow.

Quick Reference

  • Supported currencies: NGN, USD
  • Base URL: https://api.transfaar.com/api/v1
  • Authentication: HMAC (X-API-Key, X-Timestamp, X-Signature)
  • PCI model: hosted checkout, so raw card data does not touch your servers

Initialize Payment

POST /client/checkout/initialize

Request Body

json
{  "email": "customer@example.com",  "first_name": "John",  "last_name": "Doe",  "amount": "1000.00",  "currency": "NGN",  "reference": "ORDER-12345",  "redirectUrl": "https://your-website.com/payment-success",  "logoUrl": "https://your-website.com/logo.png",  "description": "Payment for order #12345",  "checkout_display_name": "My Store",  "customer_phone_number": "+2348012345678",  "metadata": {    "custom_field": "value"  }}
ParameterTypeRequiredDescription
emailstringYesCustomer email address
first_namestringYesCustomer first name
last_namestringYesCustomer last name
amountstringYesDecimal string such as "1000.00"
currencystringYesNGN or USD
referencestringYesYour unique payment reference
redirectUrlstringNoCustomer redirect destination after checkout
logoUrlstringNoMerchant logo shown on hosted checkout
descriptionstringNoPayment description
checkout_display_namestringNoMerchant name shown on checkout
customer_phone_numberstringNoCustomer phone number
metadataobjectNoOptional tracking fields

Success Response

json
{  "success": true,  "message": "Transaction Initialized Successfully",  "data": {    "access_code": "AbCdEfGhIjKlMnOpQrStUv",    "checkout_link": "https://checkout.transfaar.com/checkout/AbCdEfGh...",    "transactionRef": "TXN-123456789",    "reference": "ORDER-12345",    "redirectUrl": "https://your-website.com/payment-success",    "valid_until": "2026-05-02T12:30:00Z"  }}

Verify Payment Status

GET /client/payment/verify?reference={transaction_reference}

or, for checkout sessions, use the reference you supplied during initialization:

GET /client/payment/verify?origin_reference={your_checkout_reference}

QueryRequiredDescription
referenceRequired if origin_reference is not sentTransfaar transaction_reference returned during initialization
origin_referenceRequired if reference is not sentYour checkout reference, stored by Transfaar as origin_reference

When origin_reference is used, Transfaar resolves the matching checkout quote/transaction and returns the same response shape.

Success Response

json
{  "transaction_id": "6196e335-a293-4c9e-b292-1e1ab219ea20",  "transaction_reference": "ABA261C575EEFC76",  "status_name": "COMPLETED",  "status_id": 2,  "amount_tendered_with_fees": "1020.00",  "amount_tendered_without_fees": "1000.00",  "amount_received": "1000.00",  "source_currency": "NGN",  "target_currency": "NGN",  "payment_completed": true,  "paymentCompleted": true,  "transaction_status": "COMPLETED",  "status": "COMPLETED",  "amount": "1020.00",  "currency": "NGN",  "message": "Payment status retrieved successfully",  "provider_transaction_status": "completed",  "provider_status_reason": "Approved"}
FieldDescription
status_nameCanonical status such as PENDING, PROCESSING, COMPLETED, FAILED
amount_tendered_with_feesTotal amount charged to the customer
amount_receivedNet amount credited after fees
payment_completedBoolean completion flag

Refund Endpoints

Initiate Refund

POST /client/payment/refund

json
{  "transaction_reference": "ORDER-12345",  "refund_amount": "500.00",  "refund_reason": "Customer requested cancellation",  "business_code": "optional-business-code"}

Check Refund Status

GET /client/payment/refund/status/:refund_reference

Refund History

GET /client/payment/refund/history

Supports query parameters like page, size, start_date, and end_date.

Related Pages