CARDS

Issue Card

Create a USD virtual card for a customer, with an optional initial prefund. The card is created pending and completes asynchronously.

POST /v1/cards

Use this endpoint to

Issue a new USD virtual card to a KYC-approved customer
Kick off the async issuance flow that completes via webhook

Body parameters

Field	Type	Required	Description
`customer_id`	string	Yes	The customer's `uuid`
`label`	string	No	Shown on the card; defaults to `"<firstname> USD Card"`
`amount`	number	No	Initial prefund in USD, minimum USD 5

Note: Your business USD wallet is debited amount + the card issuance fee at request time.

Code Samples

const response = await fetch("https://sandbox.hitchpay.ng/v1/cards", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    customer_id: "CUSTOMER_UUID",
    label: "John Doe USD Card",
    amount: 20
  })
});

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

<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/cards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "customer_id" => "CUSTOMER_UUID",
    "label" => "John Doe USD Card",
    "amount" => 20
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ]
]);

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

echo $response;

import requests

url = "https://sandbox.hitchpay.ng/v1/cards"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "customer_id": "CUSTOMER_UUID",
    "label": "John Doe USD Card",
    "amount": 20
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

{
  "status": "success",
  "message": "Card issuance is being processed. Details will be available shortly.",
  "data": {
    "tracking_id": "EXTCARD…",
    "customer_uuid": "…",
    "card_id": "…",
    "label": "John Doe USD Card",
    "brand": null,
    "card_type": "virtual",
    "currency": "USD",
    "masked_pan": null,
    "last4": null,
    "exp_month": null,
    "exp_year": null,
    "cardholder_name": "JOHN DOE",
    "balance": 20.00,
    "status": "pending",
    "date_created": "1782947655"
  }
}

Card details arrive via the card-created webhook and status becomes active. If the partner bank declines the card, you receive the card-failed webhook, and the issuance debit is automatically refunded. If the partner bank rejects the request outright at the time of creation, this call returns an error, and your wallet is refunded immediately.

Errors

Code	Meaning
`INVALID_REQUEST`	Missing/invalid fields, e.g. non-positive `amount`
`UNAUTHORIZED`	Business not found or inactive
`NOT_FOUND`	Customer not found
`KYC_REQUIRED`	The customer lacks an approved government ID and/or proof of address
`KYC_INCOMPLETE`	The approved government ID is missing its document number
`INSUFFICIENT_FUNDS`	Business USD wallet balance too low
`REQUEST_FAILED`	The card partner bank rejected the request outright, wallet refunded immediately
`SERVICE_UNAVAILABLE`	Card issuing temporarily unavailable

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