CARDS

Get Card Secure Details

Return the full card details: PAN and CVV, fetched live from the partner bank. These are never stored on our side; retrieve them only when you need to display the card to the customer.

GET /v1/cards/:tracking_id/secure

Use this endpoint to

Display the full card number and CVV to the customer in your own UI
Retrieve billing address details needed for online checkout

Path parameters

Parameter	Type	Required	Description
`tracking_id`	string	Yes	Card id from Issue Card

Note: This only works once the card has finished provisioning (status: active).

Code Samples

const response = await fetch(
  "https://sandbox.hitchpay.ng/v1/cards/EXTCARD123456/secure",
  { headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" } }
);

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

<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/cards/EXTCARD123456/secure",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

url = "https://sandbox.hitchpay.ng/v1/cards/EXTCARD123456/secure"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())

Response

{
  "status": "success",
  "message": "Card details retrieved successfully.",
  "data": {
    "tracking_id": "EXTCARD…",
    "card_id": "…",
    "number": "5399831234561234",
    "cvv": "123",
    "exp_month": "08",
    "exp_year": "2029",
    "cardholder_name": "JOHN DOE",
    "brand": "visa",
    "currency": "USD",
    "balance": 25.00,
    "billing_address": {
      "line1": "…",
      "city": "…",
      "state": "…",
      "postal_code": "…",
      "country": "…"
    }
  }
}

Fields

Field	Type	Description
`tracking_id`	string	Card id
`card_id`	string	Reference used in webhook events
`number`	string	Full card number; handle carefully, never log or store
`cvv`	string	Card security code; handle carefully, never log or store
`exp_month` / `exp_year`	string	Expiry
`cardholder_name`	string	Name on the card
`brand`	string	e.g. `visa`
`currency`	string	`USD`
`balance`	number	Current card balance
`billing_address`	object	Address on file with the card partner

Errors

Code	Meaning
`UNAUTHORIZED`	Business not found or inactive
`NOT_FOUND`	Card not found
`CARD_NOT_READY`	The card is still provisioning, no `card_id` yet
`CARD_TERMINATED`	The card has been permanently closed

Important: Treat the response from this endpoint as sensitive cardholder data. Don't log, cache, or persist number or cvv anywhere in your systems.

Questions? Email [email protected]. Also on GitBook.