Quick Start

Get your credentials

You'll need two things to authenticate:

• Merchant credentials — your account email and password
• Key hash — an API key issued to your integration

These are sent on every request. See Authentication for how to encode them.

:::tip Testing? Use sandbox credentials

Email: [email protected] Password: demo123* Key-hash: BL2H6LGNEUGSXTBARA59

:::

Charge a credit card

Send a POST to /public/payment/charge with your card details and amount. The amount is in the smallest currency unit (cents for USD).

cURL
curl -X POST https://api.paywithzero.net/v1/public/payment/charge \
  -u "[email protected]:demo123*" \
  -H "key-hash: BL2H6LGNEUGSXTBARA59" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "cardNumber": "4111111111111111",
    "expirationDate": "12/26",
    "cvv": "123"
  }'

JavaScript (fetch)
const credentials = btoa("[email protected]:demo123*");

const response = await fetch(
  "https://api.paywithzero.net/v1/public/payment/charge",
  {
    method: "POST",
    headers: {
      Authorization: `Basic ${credentials}`,
      "key-hash": "BL2H6LGNEUGSXTBARA59",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 1000,
      currency: "USD",
      cardNumber: "4111111111111111",
      expirationDate: "12/26",
      cvv: "123",
    }),
  }
);

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

Handle the response

A successful charge returns HTTP 200 with a data object containing the transaction details:

Code
{
  "data": {
    "id": "txn_abc123",
    "status": "approved",
    "amount": 1000,
    "currency": "USD",
    "authCode": "ABC123",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

If the charge is declined or invalid, the API returns a 400 with an error body. Always check the HTTP status code and the response.code field. See Error Handling.

:::warning Declined transactions

A declined card returns HTTP 400. The response.code tells you the reason — for example, code 300 means "Transaction was rejected by gateway."

:::

What's next

Now that you've made your first charge, explore the rest of the API:

• Customer vault — save cards to avoid collecting them on every payment
• Subscriptions — set up recurring billing
• Refunds — reverse a transaction with POST /public/payment/refund
• Webhooks — get notified when a payment status changes