CARDS

Fund Card

Top up a card from your business USD wallet. The card must be active.

POST /v1/cards/:tracking_id/fund

Use this endpoint to

Add funds to a card so the customer can spend
Reload a card after its balance runs low

Request

Path parameters

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

Body parameters

Field	Type	Required	Description
`amount`	number	Yes	Amount in USD to add to the card

Code Samples

const response = await fetch(
  "https://sandbox.hitchpay.ng/v1/cards/EXTCARD123456/fund",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ amount: 50 })
  }
);

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/fund",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode(["amount" => 50]),
  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/EXTCARD123456/fund"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {"amount": 50}

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

Response

{
  "status": "success",
  "message": "Card funded successfully.",
  "data": {
    "tracking_id": "EXTCARD…",
    "amount": 50,
    "currency": "USD",
    "balance": 75.00,
    "reference": "CFND…"
  }
}

On a definitive partner bank failure, the wallet is auto-refunded, and you get an error instead.

Fields

Field	Type	Description
`tracking_id`	string	Card id
`amount`	number	Amount added
`currency`	string	`USD`
`balance`	number	Card balance after this top-up
`reference`	string	Our transaction id for this funding event

Errors

Code	Meaning
`INVALID_REQUEST`	Missing/invalid `amount`, e.g. non-positive
`UNAUTHORIZED`	Business not found or inactive
`NOT_FOUND`	Card not found
`INSUFFICIENT_FUNDS`	Business USD wallet balance too low
`CARD_NOT_READY`	Card is still provisioning
`CARD_NOT_ACTIVE`	Card is frozen or otherwise not active
`CARD_TERMINATED`	The card has been permanently closed
`REQUEST_FAILED`	The card partner rejected the operation wallet auto-refunded

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