Skip to main content
Initiate a card purchase by sending your customer’s card details. Card data is encrypted server-side using Interswitch’s RSA public key — you submit the raw values and the API handles all encryption before forwarding to the payment processor.

​
Endpoint

POST /api/v1/card-payments/purchase

​
Authentication

Include your API key credentials as request headers: 
x-api-key: your_api_key
x-api-secret: your_api_secret

​
Request body

​
customerId
string
required
The ID of the customer making the payment. Must be a valid customer record in your account.
​
amount
string
required
The charge amount in naira as a string. Do not include kobo — the API converts internally. For example, "1000" charges ₦1,000.
​
currency
string
required
ISO 4217 currency code. Use "NGN" for Nigerian naira.
​
transactionRef
string
required
Your unique reference for this transaction. Must be unique across all your transactions. Used to query status and correlate webhooks.
​
pan
string
required
The full card number (Primary Account Number). Transmitted in plain text to the API; the API encrypts it before passing to the processor. Do not pre-encrypt this value.
​
pin
string
required
The card PIN. Transmitted in plain text to the API; the API encrypts it server-side.
​
expiryDate
string
required
Card expiry date in YYMM format. For example, "2504" represents April 2025.
​
cvv2
string
required
The 3-digit CVV/CVV2 security code printed on the card.

​
Response codes

The data.responseCode field in a successful response indicates the next step:
CodeMeaning
00Payment approved. Transaction is complete.
T0OTP required. Proceed to Authenticate OTP (Verve / Mastercard).
S03DS authentication required. Redirect the user to the 3DS URL.

​
Example request

curl --request POST \
  --url https://api.hyparrow.com/api/v1/card-payments/purchase \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key' \
  --header 'x-api-secret: your_api_secret' \
  --data '{
    "customerId": "HYP_abc123def456gh78",
    "amount": "5000",
    "currency": "NGN",
    "transactionRef": "TXN-20240401-001",
    "pan": "5061460410120223210",
    "pin": "1234",
    "expiryDate": "2612",
    "cvv2": "111"
  }'

​
Example responses

{
  "success": true,
  "message": "Card purchase initiated",
  "data": {
    "responseCode": "T0",
    "message": "Enter OTP sent to your registered phone",
    "paymentId": "PAY-2024042310300001",
    "transactionId": "1234567890",
    "eciFlag": "07"
  }
}

​
Response fields

​
success
boolean
true when the API call succeeded (even if the card was declined — check data.responseCode).
​
message
string
A human-readable summary of the outcome.
​
data
object
The raw response from the payment processor.