API Documentation

Integrate with our card issuing platform. All API requests should be sent with the `Content-Type: application/json` header.

Authentication: All API requests must include your publickey and secretkey in the request headers.

4XXBINs

Use one consistent API to create and manage virtual cards. Available products are VISA us_addon_visa_bin (400BIN) and us_493_visa_bin (493BIN), us_493_visa_atm (ATM Support Via Contactless Google pay) and 536_master (536 Mastercard).

Every request requires the publickey and secretkey headers. Send Content-Type: application/json for requests with a JSON body.

Idempotency-Key is optional on POST requests. When supplied, reuse the same key only when safely retrying the same operation and payload.

Create Card

Create a Visa card for a cardholder.

Endpoint: POST /api/v1/cards

curl -X POST https://pagocards.com/api/v1/cards \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: UNIQUE_REQUEST_KEY" \
-d '{
  "product_code": "us_493_visa_bin",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "initial_load": 10
}'

initial_load is optional. Minimum $10 and maximum of $2500 can be specified. Amounts support up to two decimal places; any digits after the second decimal are removed without rounding (for example, 55.175678 is processed as 55.17).

493 ATM cards: Use "product_code": "us_493_visa_atm". These cards do not have an initial load amount; do not send the initial_load parameter. The $12 yearly issuance fee is charged separately.

Success response (201)

{
  "status": "success",
  "message": "Card created successfully.",
  "data": {
    "card_id": "card_01m0evv599d37vm6dgb0rhd000",
    "product_code": "us_493_visa_bin",
    "brand": "493BIN",
    "type": "virtual",
    "currency": "USD",
    "status": "active",
    "name_on_card": "John Doe",
    "email": "john@example.com",
    "last_four": "1434",
    "expiry_month": "08",
    "expiry_year": "2030",
    "balance": {
      "amount": 10000000,
      "display_amount": 10,
      "currency": "USD"
    },
    "card_number": null,
    "cvv": null,
    "created_at": "2026-08-20T05:55:54+00:00"
  }
}

Get Card

Retrieve card information and the current card balance. 493BIN card details are retrieved securely and returned in the same format as 400BIN cards.

For 493BIN cards, Pagocards securely retrieves and saves the card details when the stored PAN, CVV, or expiry is missing. Clients receive card_number, cvv, and expiry fields directly, in the same format as 400BIN cards.

Endpoint: GET /api/v1/cards/{card_id}

curl https://pagocards.com/api/v1/cards/card_01m0evv599d37vm6dgb0rhd000 \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

Success response (200)

{
  "status": "success",
  "message": "Card fetched successfully.",
  "data": {
    "card_id": "card_01m0evv599d37vm6dgb0rhd000",
    "product_code": "us_493_visa_bin",
    "brand": "493BIN",
    "type": "virtual",
    "currency": "USD",
    "status": "active",
    "name_on_card": "John Doe",
    "email": "john@example.com",
    "last_four": "1434",
    "expiry_month": "08",
    "expiry_year": "2031",
    "balance": {
      "amount": 12000000,
      "display_amount": 12,
      "currency": "USD"
    },
    "card_number": "4937241043245430",
    "cardnumber": "4937241043245430",
    "cvv": "298",
    "expiredate": "08/31",
    "created_at": "2026-08-20T05:55:54+00:00"
  }
}

Set Visa 493 ATM Card PIN

Set the PIN for an owned Visa 493 ATM card. The PIN must contain exactly 6 digits. This endpoint is available only for the us_493_visa_atm product.

Endpoint: POST /api/v1/cards/{card_id}/pin

curl -X POST https://pagocards.com/api/v1/cards/card_01m0evv599d37vm6dgb0rhd000/pin \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"pin":"123456"}'

Success response (200)

{
  "status": "success",
  "message": "Card PIN set successfully."
}

Get All Cards

Retrieve every card issued to an email address for the selected card product. Results are restricted to cards owned by the authenticated API credentials.

Endpoint: POST /api/v1/cards/getallcards

curl -X POST https://pagocards.com/api/v1/cards/getallcards \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "email": "john@example.com",
  "product_code": "us_addon_visa_bin"
}'

Success response (200)

{
  "cards": [
    {
      "cardid": "card_01m0evv599d37vm6dgb0rhd000",
      "useremail": "john@example.com",
      "lastfour": "4225",
      "brand": "visa",
      "type": "virtual"
    }
  ]
}

Fund Card

Add a USD amount to a card. Amounts support up to two decimal places; any digits after the second decimal are removed without rounding (for example, 55.175678 is processed as 55.17).

Endpoint: POST /api/v1/cards/{card_id}/fund

curl -X POST https://pagocards.com/api/v1/cards/card_01m0evv599d37vm6dgb0rhd000/fund \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: UNIQUE_REQUEST_KEY" \
-d '{
  "amount": 10
}'

Success response (200)

{
  "status": "success",
  "message": "Card funded successfully.",
  "data": {
    "card_id": "card_01m0evv599d37vm6dgb0rhd000",
    "amount": 10000000,
    "display_amount": 10,
    "currency": "USD",
    "status": "completed",
    "transaction_id": "20260825123456789"
  }
}

Withdraw 4XX-BIN Card

Withdraw USD from a 400BIN or 493BIN card. After the vendor confirms the withdrawal, the same amount is credited to your 400BIN wallet. No withdrawal fee is charged by Pagocards.

Endpoint: POST /api/v1/cards/{card_id}/withdraw

curl -X POST https://pagocards.com/api/v1/cards/card_01m0evv599d37vm6dgb0rhd000/withdraw \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{"amount": 10}'

{
  "status": "success",
  "message": "Card withdrawal completed successfully.",
  "data": {
    "card_id": "card_01m0evv599d37vm6dgb0rhd000",
    "amount": 10000000,
    "display_amount": 10,
    "currency": "USD",
    "status": "completed",
    "transaction_id": "WD20260826123456789",
    "wallet_transaction_id": "wallet-credit-transaction-uuid"
  }
}

Terminate 4XX-BIN Card

Permanently terminate a 400BIN or 493BIN card.

Ensure you withdraw the balance before terminating a card, otherwise it can take up to 45 days for the card balance refund.

Endpoint: POST /api/v1/cards/{card_id}/terminate

curl -X POST https://pagocards.com/api/v1/cards/card_01m0evv599d37vm6dgb0rhd000/terminate \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

{
  "status": "success",
  "message": "Card terminated successfully.",
  "data": {"card_id": "card_01m0evv599d37vm6dgb0rhd000", "status": "terminated"}
}

Block Card

Temporarily prevent transactions on a card.

Endpoint: POST /api/v1/cards/{card_id}/block

curl -X POST https://pagocards.com/api/v1/cards/card_01m0evv599d37vm6dgb0rhd000/block \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: UNIQUE_REQUEST_KEY"

Success response (200)

{
  "status": "success",
  "message": "Card blocked successfully.",
  "data": {
    "card_id": "card_01m0evv599d37vm6dgb0rhd000",
    "status": "blocked"
  }
}

Unblock Card

Restore transactions on a blocked card.

Endpoint: POST /api/v1/cards/{card_id}/unblock

curl -X POST https://pagocards.com/api/v1/cards/card_01m0evv599d37vm6dgb0rhd000/unblock \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: UNIQUE_REQUEST_KEY"

Success response (200)

{
  "status": "success",
  "message": "Card unblocked successfully.",
  "data": {
    "card_id": "card_01m0evv599d37vm6dgb0rhd000",
    "status": "active"
  }
}

Get Transactions

Retrieve card transactions. Use the optional pageNum query parameter; it defaults to page 1. Card issuance records are excluded.

Endpoint: GET /api/v1/cards/{card_id}/transactions?pageNum=1

curl "https://pagocards.com/api/v1/cards/card_01m0evv599d37vm6dgb0rhd000/transactions?pageNum=1" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

Success response (200)

{
  "status": "success",
  "message": "Transactions fetched successfully.",
  "data": {
    "transactions": [
      {
        "id": "260820000000002879",
        "card_id": "card_01m0evv599d37vm6dgb0rhd000",
        "type": "authorization",
        "status": "completed",
        "amount": 460000,
        "display_amount": 0.46,
        "currency": "USD",
        "transCurrencyAmt": "5.00",
        "transCurrency": "THB",
        "feeAmount": "0.30000000",
        "feeCurrency": "USD",
        "merchant_name": "Grab",
        "merchant_mcc": "4121",
        "reference": "53972260820000000002879",
        "created_at": "2026-08-20T05:55:00Z"
      }
    ],
    "pagination": {
      "type": "page",
      "page_num": 1,
      "page_size": 1,
      "total": 1,
      "has_more": false
    }
  }
}

Error Responses

Errors use a stable machine-readable code. Validation errors also include an errors object.

{
  "status": "failure",
  "message": "Card not found.",
  "code": "CARD_NOT_FOUND"
}

{
  "status": "failure",
  "message": "The request data is invalid.",
  "code": "VALIDATION_ERROR",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

Card Webhooks

Card events are forwarded to the webhook URL configured on your account. Store and deduplicate events using event_id, and return a 2xx response promptly. Events can be retried or arrive out of order.

Normalized event names currently include virtualcard.topup.completed, virtualcard.transaction.authorization, virtualcard.transaction.settlement, virtualcard.transaction.refund, virtualcard.transaction.fee, virtualcard.transaction.cash_withdrawal, virtualcard.transaction.card_application, and virtualcard.transaction.cancellation. Fields without a value are returned as null.

For transactionCreated events, transStatus is the vendor value: 0 initialization, 1 processing, 2 success, and 3 fail. The transType values are 170 consumption, 174 pre-authorization, 171 refund, 172 transaction fee, 173 ATM cash withdrawal, 140 card application, 150 card top-up, and 175 card cancellation.

transType	Meaning	Forwarded event
170	Card consumption	`virtualcard.transaction.settlement`
174	Card pre-authorization	`virtualcard.transaction.authorization`
171	Card refund	`virtualcard.transaction.refund`
172	Card transaction fee	`virtualcard.transaction.fee`
173	Card ATM cash withdrawal	`virtualcard.transaction.cash_withdrawal`
140	Apply for a card	`virtualcard.transaction.card_application`
150	Card top-up	`virtualcard.topup.completed`
175	Card cancellation	`virtualcard.transaction.cancellation`

Card top-up completed

{
  "data": {
    "amount": 15000000,
    "cardId": "102397",
    "companyId": null,
    "isTerminated": null,
    "narrative": null,
    "transaction_id": "202608191011134333202",
    "status": "completed"
  },
  "event": "virtualcard.topup.completed",
  "event_id": "530d8c82da7548c69230c57de20b4264",
  "cardid": "card_01m0evv599d37vm6dgb0rhd000"
}

Transaction authorization

{
  "data": {
    "amount": 34360000,
    "cardId": "102397",
    "companyId": null,
    "currency": "USD",
    "display_amount": 34.36,
    "id": "260819000000000001",
    "localCurrency": "USD",
    "localCurrencyAmt": "34.36",
    "merchant_country": null,
    "merchant_mcc": "5411",
    "merchant_name": "Example Merchant",
    "narrative": "Authorization at Example Merchant",
    "reason": "Approve",
    "reference": "CARD_AUTH_REFERENCE",
    "status": "completed",
    "timestamp": "2026-08-19T12:04:27Z",
    "transCurrency": "USD",
    "transCurrencyAmt": "34.36",
    "transaction_type": "authorization"
  },
  "event": "virtualcard.transaction.authorization",
  "event_id": "556eeda53cdd4a07a562a9f9b77d7438",
  "cardid": "card_01m0evv599d37vm6dgb0rhd000"
}

Settlement events use virtualcard.transaction.settlement and settlement as the transaction type.

Authorization fee

When a card has insufficient balance for an authorization fee, the fee is debited from the Visa wallet and forwarded in this format.

{
  "data": {
    "amount": 300000,
    "cardId": "55363",
    "currency": "USD",
    "display_amount": 0.3,
    "id": "FEE55363260821000000006168",
    "narrative": "Authorization fee",
    "reference": "FEE55363260821000000006168",
    "status": "completed",
    "timestamp": "2026-08-20T00:36:13Z",
    "transaction_type": "authorization_fee"
  },
  "event": "virtualcard.authorization.fee",
  "event_id": "dce7e10abb504bf38bc4e82494872887",
  "cardid": "card_01m0evv599d37vm6dgb0rhd000"
}

3DS event

3DS events are automatically submitted for approval and are also forwarded to your configured webhook URL in the following format.

{
  "eventId": "977bdaf833a8423186d599cee720cf29",
  "eventType": "3ds",
  "userBankcardId": 1000001,
  "verificationType": "http",
  "otp": "234562",
  "authId": "b47621b3601a4052951f8c5a8fe430b6",
  "transactionAmount": "10",
  "transactionCurrency": "USD",
  "merchantName": "MYPAL",
  "cardid": "card_01m0evv599d37vm6dgb0rhd000"
}

EURO-MASTER API

Use these endpoints to issue, retrieve, fund, freeze, unfreeze, and inspect EUR virtual Mastercard cards. All requests require publickey and secretkey headers.

Create Card

Issue a new EURO-MASTER virtual card. The issuance fee is debited from the funding wallet.

Endpoint: POST /api/createcard

Request Body Parameters:

firstName (required): Cardholder first name
lastName (required): Cardholder last name
email (required): Cardholder email address

curl -X POST https://pagocards.com/api/createcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "firstName": "John",
  "lastName": "Doe",
  "email": "joe@doe.com"
}'

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "joe@doe.com"
}

{
  "cardid": "6a2aa482e9458beedaf70636",
  "useremail": "joe@doe.com",
  "nameoncard": "John Doe"
}

Get Card

Retrieve current status, balance, currency, and stored card metadata.

Endpoint: POST /api/getcard

Request Body Parameters:

cardid (required): Card ID returned from create card
email (required): Cardholder email address

curl -X POST https://pagocards.com/api/getcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}'

{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}

{
  "cardid": "6a2aa482e9458beedaf70636",
  "useremail": "joe@doe.com",
  "nameoncard": "John Doe",
  "brand": "newmaster",
  "type": "virtual",
  "currency": "EUR",
  "status": "active",
  "balance": 1.7
}

Get All Cards

Retrieve all EURO-MASTER cards for a specific cardholder email.

Endpoint: POST /api/getallcards

Request Body Parameters:

email (required): Cardholder email address

curl -X POST https://pagocards.com/api/getallcards \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "email": "joe@doe.com"
}'

{
  "email": "joe@doe.com"
}

{
  "cards": [
    {
      "cardid": "6a2aa482e9458beedaf70636",
      "useremail": "joe@doe.com",
      "lastfour": "1234",
      "brand": "newmaster",
      "type": "virtual"
    }
  ]
}

Get Exchange Rate

Retrieve the current FX rate used for EURO-MASTER wallet to card conversions.

Endpoint: GET /api/getfx

Headers:

publickey (required): Your public API key
secretkey (required): Your secret API key

curl -X GET https://pagocards.com/api/getfx \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

{
  "status": "success",
  "fx": {
    "rate": 0.92,
    "comission": 0,
    "value": 0.92
  }
}

Get Sensitive

Retrieve a signed JavaScript embed URL that displays sensitive card details in an iframe.

Endpoint: POST /api/getcardsensitive

Request Body Parameters:

cardid (required): Card ID returned from create card
email (required): Cardholder email address

curl -X POST https://pagocards.com/api/getcardsensitive \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}'

{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}

{
  "cardid": "6a2aa482e9458beedaf70636",
  "useremail": "joe@doe.com",
  "cardnumber": "",
  "cvc" : "",
  "month": "",
  "url": "https://pagocards.com/api/cards/sensitive/embed.js?payload=...&signature=...",
  "message": "Embed this card details URL in a <script src='<url>'></script> tag in your card details screen to display sensitive card information."
}

Fund Card

Fund a EURO-MASTER card. Send the original USDC amount. The live USDC to EUR rate is fetched when the transfer executes.

Endpoint: POST /api/fundcard

Request Body Parameters:

cardid (required): Card ID returned from create card
email (required): Cardholder email address
amount (required): Amount in USDC. Minimum is 3.

curl -X POST https://pagocards.com/api/fundcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com",
  "amount": 25
}'

{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com",
  "amount": 25
}

{
  "status": "success",
  "reference": "PGC-REFERENCE",
  "transaction_id": "provider-transaction-id",
  "amount": 25,
  "amount_eur": 21.25,
  "fee": 1.25,
  "code": 200
}

Withdraw from Card

Withdraw funds from a EURO-MASTER card. The amount is returned to your funding wallet, minus a $1 fee.

Endpoint: POST /api/withdraw

Request Body Parameters:

cardid (required): Card ID
email (required): Cardholder email address
amount (required): Amount in USDC to withdraw. Must be greater than 1.

curl -X POST https://pagocards.com/api/withdraw \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com",
  "amount": 10
}'

{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com",
  "amount": 10
}

{
  "status": "success",
  "cardid": "6a2aa482e9458beedaf70636",
  "useremail": "joe@doe.com",
  "euro_amount": 7.5,
  "usdc_amount": 9,
  "transactionId": "provider-transaction-id"
}

Get Transactions

Retrieve paginated transactions for a EURO-MASTER card.

Endpoint: POST /api/gettransactions

Request Body Parameters:

cardid (required): Card ID returned from create card
email (required): Cardholder email address
page (optional): Page number
limit (optional): Number of transactions per page
dateFrom, dateTo, types, dateSort (optional): Provider transaction filters

curl -X POST https://pagocards.com/api/gettransactions \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com",
  "page": 1,
  "limit": 10
}'

{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com",
  "page": 1,
  "limit": 10
}

{
  "status": "success",
  "data": {
    "transactions": [
      {
        "id": "60a7c8b5f1d2c3a5b4e3f678",
        "amount": 100.5,
        "currency": "USD",
        "settledAmount": 110.5,
        "merchant": "MERCHANT",
        "mcc": "0000",
        "type": ["AUTHORIZATION"],
        "status": ["APPROVED"],
        "transactionDate": "2024-03-24T12:34:56.789Z",
        "clearingTransactionDate": "2024-03-24T12:34:56.789Z",
        "declineReason": null
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "pages": 3,
      "total": 22
    }
  }
}

Block Card

Freeze a EURO-MASTER card.

Endpoint: POST /api/blockcard

curl -X POST https://pagocards.com/api/blockcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}'

{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}

Unblock Card

Unfreeze a EURO-MASTER card.

Endpoint: POST /api/unblockcard

curl -X POST https://pagocards.com/api/unblockcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}'

{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}

Terminate Card

Permanently terminate a EURO-MASTER card. A $1 fee is applicable.

Endpoint: POST /api/terminatecard

curl -X POST https://pagocards.com/api/terminatecard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}'

{
  "cardid": "6a2aa482e9458beedaf70636",
  "email": "joe@doe.com"
}

Webhooks

EURO-MASTER webhook events are sent to your configured webhook URL. The payload structure depends on the event type.

Transaction Event

{
  "type": "transaction",
  "data": {
    "cardId": "string",
    "id": "string",
    "amount": "number",
    "currency": "string",
    "settledAmount": "number",
    "merchant": "string",
    "transactionDate": "date",
    "clearingDate": "date",
    "declineReason": "string",
    "type": ["AUTHORIZATION", "REFUND"],
    "status": ["APPROVED", "FAILED", "CLEARED"],
    "mcc": "string",
    "merchantId": "string",
    "merchantCountry": "string"
  }
}

Extra Fee Event

{
  "type": "extraFee",
  "data": {
    "type": ["transaction"],
    "amount": "number",
    "currency": "string",
    "settledAmount": "number",
    "cardId": "string",
    "from": ["master-account", "card"],
    "status": ["success"]
  }
}

Card Issue Event

{
  "type": "card-issue",
  "data": {
    "id": "string",
    "status": "success | failed"
  }
}

3DS Event

{
  "status": "success",
  "type": "3ds",
  "data": {
    "id": "string",
    "status": ["APPROVED", "DECLINED", "PENDING"],
    "amount": {
      "amount": "number",
      "currency": "string"
    },
    "merchant": {
      "name": "string",
      "country": "string"
    },
    "card": {
      "cardId": "string"
    }
  }
}

Card State Event

{
  "status": "success",
  "type": "card-state",
  "data": {
    "id": "string",
    "cardBalance": "number",
    "maskedCardNumber": "string",
    "status": ["active", "deleted", "freezed", "pending", "failed", "expired", "blocked"]
  }
}

Visacard API

An Initial Loading of $3 is required per card issuance. If your user card balance is insufficient, Decline Fees and Cross border fees will be debited from your main wallet. Decline Fees: $0.75 (second onwards), FX Fee: 2% + $0.5

Incase you get a failed topup webhook, do not retry the topup or refund, it will be auto retried by us, if you retry the topup, the card will have a second loading of funds.

Create Visacard

Creates a new virtual Visacard.

Endpoint: POST /api/visacard/createcard

curl -X POST https://pagocards.com/api/visacard/createcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "firstname": "Jane",
  "lastname": "Doe",
  "email": "jane.doe@example.com"
}'

{
  "firstname": "Jane",
  "lastname": "Doe",
  "email": "jane.doe@example.com"
}

Fund Visacard

Incase you receive a webhook of topup failed, do not retry the topup, it will duplicate the fund loading, failed topups are auto retried

Endpoint: POST /api/visacard/fundcard

curl -X POST https://pagocards.com/api/visacard/fundcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "card_yyyyyyyyyyyy",
  "email": "jane.doe@example.com",
  "amount": 25
}'

{
  "cardid": "card_yyyyyyyyyyyy",
  "email": "jane.doe@example.com",
  "amount": 25
}

Get Card Details

Retrieves details for a specific Visacard.

Endpoint: POST /api/visacard/getcard

curl -X POST https://pagocards.com/api/visacard/getcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "email": "jane.doe@example.com",
  "cardid": "card_yyyyyyyyyyyy"
}'

{
  "email": "jane.doe@example.com",
  "cardid": "card_yyyyyyyyyyyy"
}

Get All Cards

Retrieves a list of all Visacards for a specific user email.

Endpoint: POST /api/visacard/getallcards

curl -X POST https://pagocards.com/api/visacard/getallcards \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "email": "jane.doe@example.com"
}'

{
  "email": "jane.doe@example.com"
}

Block / Unblock Card

Blocks or unblocks a specific Visacard.

Endpoints:

POST /api/visacard/blockcard
POST /api/visacard/unblockcard

curl -X POST https://pagocards.com/api/visacard/blockcard \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "email": "jane.doe@example.com",
  "cardid": "card_yyyyyyyyyyyy"
}'

{
  "email": "jane.doe@example.com",
  "cardid": "card_yyyyyyyyyyyy"
}

Spend Controls

Update spending limits and merchant/category controls for a Visa card. All spend-limit fields are optional.

Endpoint: PUT /api/visacard/spendcontrols

Request Body Parameters:

cardid (required): The unique identifier of the card
email (required): The email address of the card owner
single_transaction (optional): Single transaction limit
daily (optional): Daily spending limit
weekly (optional): Weekly spending limit
monthly (optional): Monthly spending limit
allowed_categories (optional): Allowed categories array
blocked_categories (optional): Blocked categories array
allowed_merchants (optional): Allowed merchants array
blocked_merchants (optional): Blocked merchants array

curl -X PUT https://pagocards.com/api/visacard/spendcontrols \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "card_yyyyyyyyyyyy",
  "email": "jane.doe@example.com",
  "single_transaction": "2000.00",
  "daily": "10000.00",
  "weekly": "40000.00",
  "monthly": "100000.00",
  "allowed_categories": ["travel", "software", "office_supplies"],
  "blocked_categories": ["gambling", "adult_content"],
  "allowed_merchants": [],
  "blocked_merchants": ["merchant_123"]
}'

{
  "cardid": "card_yyyyyyyyyyyy",
  "email": "jane.doe@example.com",
  "single_transaction": "2000.00",
  "daily": "10000.00",
  "weekly": "40000.00",
  "monthly": "100000.00",
  "allowed_categories": ["travel", "software", "office_supplies"],
  "blocked_categories": ["gambling", "adult_content"],
  "allowed_merchants": [],
  "blocked_merchants": ["merchant_123"]
}

{
  "status": "success",
  "message": "Spending limits updated successfully",
  "code": 200,
  "data": {
    "card_id": "card_yyyyyyyyyyyy",
    "operation": "update_spending_limits",
    "spending_limits": {
      "single_transaction": "2000.00",
      "daily": "10000.00",
      "weekly": "40000.00",
      "monthly": "100000.00",
      "allowed_categories": ["travel", "software", "office_supplies"],
      "blocked_categories": ["gambling", "adult_content"],
      "allowed_merchants": [],
      "blocked_merchants": ["merchant_123"]
    },
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Restricted MCC

The following MCCs are restricted for Visa card transactions. Certain transactions may be declined based on the risk assesment by the acquirers and the bank if a merchant MID has been flagged or has a high risk / fraud score.

MCC	Description
`5815`	Digital streaming services (Only if local card usage restrictions exists in some countries)
`7995`	Gambling, betting, online gaming
`6051`	Crypto, foreign exchange, debt repayment
`7273`	Dating services
`5966`	Telemarketing
`7801 / 7802`	US-based licensed casinos, racing, government lotteries
`4829`	Peer-to-peer money transfer platforms
`6211`	Securities and brokerage payments

Terminate Card

Terminate a Visa card by sending a deletion request.

Endpoint: POST /api/terminate

Headers:

publickey (required): Your public API key
secretkey (required): Your secret API key
Content-Type: application/json

Request Body Parameters:

cardid (required): The unique identifier of the card to terminate
email (required): The email address of the card owner

curl -X POST https://pagocards.com/api/terminate \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "cardid": "card_abc123xyz",
  "email": "user@example.com"
}'

{
  "cardid": "card_abc123xyz",
  "email": "user@example.com"
}

See POSTMAN collection

Giftcards API

Get All Giftcards

Retrieve a paginated list of all available giftcards in the catalog. You can filter the results using query parameters.

Endpoint: GET /api/getgiftcards

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Number of items per page (default: 20)
search (optional): Search by title, currency, or region
country (optional): Filter by region/country
currency (optional): Filter by exact currency code (e.g., USD)

curl -X GET "https://pagocards.com/api/getgiftcards?page=1&limit=20&search=amazon" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

Get Giftcard By SKU

Retrieve details of a specific giftcard using its SKU.

Endpoint: GET /api/getgiftcard/{sku}

curl -X GET https://pagocards.com/api/getgiftcard/1000 \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

Get Exchange Rates

Fetch the current exchange rates required if purchasing giftcards priced in currencies other than USD.

Endpoint: GET /api/getexchangerates

curl -X GET https://pagocards.com/api/getexchangerates \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

Check SKU Availability

Verify if a specific quantity and price of a giftcard SKU is available for purchase before placing an order.

Endpoint: GET /api/checkskuavailability/{sku}?item_count=1&price=10.00

curl -X GET "https://pagocards.com/api/checkskuavailability/1000?item_count=1&price=25.00" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

Purchase Giftcard

Purchase a giftcard using the user's giftcard wallet balance. The total cost is automatically deducted.

Endpoint: POST /api/purchasegiftcard

curl -X POST https://pagocards.com/api/purchasegiftcard \
-H "Content-Type: application/json" \
-d '{
  "sku": "1000",
  "quantity": 1,
  "amount": 25.00,
  "publickey": "YOUR_PUBLIC_KEY",
  "secretkey": "YOUR_SECRET_KEY"
}'

{
  "sku": "1000",
  "quantity": 1,
  "amount": 25.00,
  "publickey": "YOUR_PUBLIC_KEY",
  "secretkey": "YOUR_SECRET_KEY"
}

Get Giftcard Order

Retrieve details and the share link for a specific purchased giftcard order using its reference code.

Endpoint: GET /api/getgiftcardorder/{referencecode}

curl -X GET https://pagocards.com/api/getgiftcardorder/01c79b97-8ab4-423c-a11d-225897f2135a \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

Get Giftcard Order History

Retrieve a paginated list of all giftcard purchase records associated with the API key.

Endpoint: GET /api/getgiftcardorderhistory

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Number of items per page (default: 20)

curl -X GET "https://pagocards.com/api/getgiftcardorderhistory?page=1&limit=20" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

Payouts API

Use these endpoints to retrieve indicative FX rates, create payout quotes, and initialize payouts. Quote and transfer requests require publickey and secretkey headers.

USD ACH payouts to US banks and EUR SEPA Instant payouts to supported EU countries are available.

Idempotency-Key is an optional header on the vendor-backed ACH and SEPA endpoints below. Use a new unique value, such as a UUID, for each logical request. When retrying the same request, reuse the same value so a previously successful response can be returned without repeating the vendor operation or wallet debit.

SEPA FX rates

Retrieve the latest indicative EUR spot rates for the supported SEPA source-amount bands. This endpoint does not require API key headers.

Endpoint: GET /api/sepa/getFX

curl -X GET https://pagocards.com/api/sepa/getFX \
-H "Accept: application/json"

{
  "status": "success",
  "message": "rates fetched successfully",
  "25-2499": "0.9212345678",
  "2500-3499": "0.9223456789",
  "3500-4999": "0.9234567890",
  "5000-7500": "0.9245678901",
  "note": "The rates displayed above are not final, the final rates would apply when creating and executing a quote with beneficiary details."
}

A rate is returned as null if its amount band has not yet been refreshed.

SEPA payout quote

Create a SEPA Instant quote. The SEPA wallet must cover the source amount plus the displayed transfer fee.

Endpoint: POST /api/sepa/getquote

curl -X POST https://pagocards.com/api/sepa/getquote \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
  "sourceAmount": 100,
  "destinationCountry": "DE",
  "nickname": "TEST USER",
  "bank_name": "Partner Clearing Bank",
  "iban": "DE0520220800005233445574",
  "bic_swift": "SXPYDEHH",
  "street": "Banking Circle German Branch",
  "city": "Munich",
  "state_province": "BY",
  "postal_code": "80538"
}'

{
  "sourceAmount": 100,
  "destinationCountry": "DE",
  "nickname": "TEST USER",
  "bank_name": "Partner Clearing Bank",
  "iban": "DE0520220800005435343574",
  "bic_swift": "SXPYDEHH",
  "street": "Banking Circle German Branch",
  "city": "Munich",
  "state_province": "BY",
  "postal_code": "80538"
}

{
  "success": true,
  "quoteId": "quote_example",
  "sourceAmount": 100,
  "sourceCurrency": "USDC",
  "targetCurrency": "EUR",
  "final_amount": "85.22",
  "transferfee": 3.55,
  "beneficiary_name": "TEST USER",
  "bank_name": "Partner Clearing Bank",
  "iban": "DE0520220800005233445574",
  "bic_swift": "SXPYDEHH",
  "expiresAt": "2026-08-16T16:23:44+00:00",
  "quoteValiditySeconds": 420
}

SEPA confirm transfer

Confirm a stored SEPA quote, debit the SEPA wallet, and initiate its USDC settlement.

Endpoint: POST /api/sepa/transfer

curl -X POST https://pagocards.com/api/sepa/transfer \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
-d '{"quoteid":"quote_example"}'

{
  "quoteid": "quote_example"
}

{
  "success": true,
  "quoteId": "quote_example",
  "sourceAmount": 100,
  "sourceCurrency": "USDC",
  "targetCurrency": "EUR",
  "final_amount": "85.22",
  "transferfee": 3.55,
  "beneficiary_name": "TEST USER",
  "bank_name": "Partner Clearing Bank",
  "iban": "DE05202208000052234234574",
  "bic_swift": "SXPYDEHH",
  "expiresAt": "2026-08-16T16:30:04.867Z",
  "quoteValiditySeconds": 420,
  "transferId": "ord_example",
  "payoutRail": "SEPA_INSTANT"
}

SEPA transfer status

Retrieve the latest status and settlement details for a transfer using its vendor transfer UUID.

Endpoint: GET /api/sepa/getstatus/{transferUuid}

Headers:

publickey (required): Your public API key
secretkey (required): Your secret API key
Idempotency-Key (optional): A unique value reused only when retrying this exact request

Path parameter:

transferUuid (required): The transfer UUID returned by the vendor, for example sp_tx_usdc_msymjrx8vj9j.

curl -X GET https://pagocards.com/api/sepa/getstatus/sp_tx_usdc_msymjrx8vj9j \
-H "Accept: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440002"

{
  "success": true,
  "transaction": {
    "transferUUID": "sp_tx_usdc_msymjrx8vj9j",
    "beneficiaryName": "BlueBanc LLC",
    "status": "COMPLETED",
    "sourceAsset": "USDC",
    "sourceAmount": 50,
    "targetCurrency": "USD",
    "final_amount": "50",
    "destination_currency": "USD",
    "spotRate": 1,
    "payoutRail": "Instant Bank Clearing",
    "quoteId": "transfer_aTqVxd81jBEdGhDlhEdVe74CEOnrKfqFIJffeALA",
    "bankAccountDetails": {
      "bank_name": "SUTTON BANK",
      "account_number": "30459613",
      "routing_number": "041208777",
      "account_holder_name": "BlueBanc LLC"
    },
    "destinationCountry": "US",
    "updated_at": "2026-08-18T12:31:00+00:00"
  }
}

ACH payout quote

Endpoint: POST /api/payouts/getpayoutquote

curl -X POST https://pagocards.com/api/payouts/getpayoutquote \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440003" \
-d '{
  "to_currency": "USD",
  "country": "US",
  "amount": "1000"
}'

{
  "to_currency": "USD",
  "country": "US",
  "amount": "1000"
}

ACH confirm transfer

Initialize and finalize a payout for an existing quote.

Endpoint: POST /api/payouts/{quoteId}/initialize

Allowed Values:

account_type: checking or savings
beneficiary.type: individual or business

curl -X POST https://pagocards.com/api/payouts/QT2_21362485/initialize \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440004" \
-d '{
  "account_type": "checking",
  "account_number": "0123456789",
  "routing_number": "021000021",
  "bank_name": "Access Bank",
  "bank_address": "123 Main Street",
  "post_code": "10001",
  "city": "New York",
  "state": "New York",
  "country": "US",
  "beneficiary": {
    "type": "individual",
    "account_name": "Test Beneficiary",
    "state": "new  york",
    "city": "new  york",
    "address": "456 Elm Street",
    "post_code": "100001"
  }
}'

{
  "account_type": "checking",
  "account_number": "0123456789",
  "routing_number": "021000021",
  "bank_name": "Access Bank",
  "bank_address": "123 Main Street",
  "post_code": "10001",
  "city": "New York",
  "state": "New York",
  "country": "US",
  "beneficiary": {
    "type": "individual",
    "account_name": "Test Beneficiary",
    "state": "new  york",
    "city": "new  york",
    "address": "456 Elm Street",
    "post_code": "100001"
  }
}

alabama
alaska
american_samoa
arizona
arkansas
california
colorado
connecticut
delaware
district_of_columbia
florida
georgia
guam
hawaii
idaho
illinois
indiana
iowa
kansas
kentucky
louisiana
maine
maryland
massachusetts
michigan
minnesota
mississippi
missouri
montana
nebraska
nevada
new_hampshire
new_jersey
new_mexico
new_york
north_carolina
north_dakota
northern_mariana_islands
ohio
oklahoma
oregon
pennsylvania
puerto_rico
rhode_island
south_carolina
south_dakota
tennessee
texas
united_states_minor_outlying_islands
utah
vermont
virgin_islands_us
virginia
washington
west_virginia
wisconsin
wyoming

Admin API

Use these endpoints to retrieve wallet balances, transactions, deposits, and issued cards tied to the provided admin API keys.

Get Admin Balance

Retrieve the current funding, visa, and giftcard wallet balances for the authenticated admin account.

Endpoint: GET /api/admin/balance

Headers:

publickey (required): Your public API key
secretkey (required): Your secret API key

curl -X GET https://pagocards.com/api/admin/balance \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

{
  "status": "success",
  "master_wallet_balance": 250.5,
  "visa_wallet_balance": 100.25,
  "giftcard_wallet_balance": 40,
  "sepa_wallet_balance": 5000
}

Get Admin Transactions

Retrieve paginated transactions for the authenticated admin account. Results can be filtered by transaction UUID and description text.

Endpoint: GET /api/admin/transactions

Headers:

publickey (required): Your public API key
secretkey (required): Your secret API key

Query Parameters:

page_number (optional): Page number (default: 1)
per_page (optional): Items per page (default: 20, max: 100)
uuid (optional): Exact match against the transaction uuid column
searchterm (optional): Partial match against the transaction description column

curl -X GET "https://pagocards.com/api/admin/transactions?page_number=1&per_page=20&uuid=0c3b2f4a-1111-2222-3333-444455556666&searchterm=funding" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

{
  "status": "success",
  "total": 1,
  "per_page": 20,
  "current_page": 1,
  "total_pages": 1,
  "transactions": [
    {
      "uuid": "0c3b2f4a-1111-2222-3333-444455556666",
      "description": "Wallet funding",
      "amount": "50.00"
    }
  ]
}

Get Admin Deposits

Retrieve paginated deposit records for the authenticated admin account.

Endpoint: GET /api/admin/deposits

Headers:

publickey (required): Your public API key
secretkey (required): Your secret API key

Query Parameters:

page_number (optional): Page number (default: 1)
per_page (optional): Items per page (default: 15, max: 100)

curl -X GET "https://pagocards.com/api/admin/deposits?page_number=1&per_page=15" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY"

{
  "status": "success",
  "total": 1,
  "per_page": 15,
  "current_page": 1,
  "total_pages": 1,
  "deposits": [
    {
      "amount": "100.00",
      "status": "success"
    }
  ]
}

Get All Admin Cards

Retrieve issued cards associated with the authenticated admin API keys. Results can be filtered by brand.

Endpoint: POST /api/admin/allcards

Headers:

publickey (required): Your public API key
secretkey (required): Your secret API key

Request Body Parameters:

brand (optional): Filter by visa or master
per_page (optional): Number of cards per page (default: 15)

curl -X POST https://pagocards.com/api/admin/allcards \
-H "Content-Type: application/json" \
-H "publickey: YOUR_PUBLIC_KEY" \
-H "secretkey: YOUR_SECRET_KEY" \
-d '{
  "brand": "visa",
  "per_page": 20
}'

{
  "brand": "visa",
  "per_page": 20
}

{
  "status": "success",
  "message": "Cards retrieved successfully",
  "data": {
    "total": 1,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 1,
    "cards": [
      {
        "cardid": "card_123",
        "useremail": "joe@doe.com",
        "lastfour": "1234",
        "brand": "visa",
        "type": "virtual",
        "status": "active"
      }
    ]
  },
  "code": 200
}