Documentation API

API Visa et Mastercard

Ces endpoints permettent de creer et gerer les cartes Visa et Mastercard virtuelles prises en charge par Goodpay.

Créer une carte

Crée une carte Visa ou Mastercard pour un utilisateur final. Débit: 5 USD de chargement automatique + 1,50 USD de frais de recharge + frais de création admin. Idempotency-Key est obligatoire.

Endpoint: POST /createcard

curl -X POST https://magowallet.com/api/visa/createcard
-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",
  "firstname": "Jane",
  "lastname": "Doe",
  "email": "jane.doe@example.com",
  "external_user_id": "customer-1001",
  "reference": "order-card-1001"
}'

{
  "product_code": "us_493_visa_bin",
  "firstname": "Jane",
  "lastname": "Doe",
  "email": "jane.doe@example.com",
  "external_user_id": "customer-1001",
  "reference": "order-card-1001"
}

Recharger une carte

Recharge une carte Visa Gold ou Mastercard Gold. Minimum: 5 USD.

Endpoint: POST /fundcard

curl -X POST https://magowallet.com/api/visa/fundcard
-H "Content-Type: application/json" 
-H "publickey: YOUR_PUBLIC_KEY" 
-H "secretkey: YOUR_SECRET_KEY" 
-H "Idempotency-Key: UNIQUE_REQUEST_KEY" 
-d '{
  "cardid": "card_01m0evv599d37vm6dgb0rhd000",
  "email": "jane.doe@example.com",
  "amount": 25,
  "from_currency": "USD"
}'

{
  "cardid": "card_01m0evv599d37vm6dgb0rhd000",
  "email": "jane.doe@example.com",
  "amount": 25,
  "from_currency": "USD"
}

Obtenir les détails de carte

Récupère les détails et le solde de la carte demandée.

Endpoint: POST /getcarddetails

curl -X POST https://magowallet.com/api/visa/getcarddetails
-H "Content-Type: application/json" 
-H "publickey: YOUR_PUBLIC_KEY" 
-H "secretkey: YOUR_SECRET_KEY" 
-d '{
  "cardid": "card_01m0evv599d37vm6dgb0rhd000",
  "email": "jane.doe@example.com"
}'

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

Obtenir toutes les cartes

Récupère les cartes appartenant au client pour le produit sélectionné.

Endpoint: POST /getallcards

curl -X POST https://magowallet.com/api/visa/getallcards
-H "Content-Type: application/json" 
-H "publickey: YOUR_PUBLIC_KEY" 
-H "secretkey: YOUR_SECRET_KEY" 
-d '{
  "email": "jane.doe@example.com",
  "product_code": "us_493_visa_bin"
}'

{
  "email": "jane.doe@example.com",
  "product_code": "us_493_visa_bin"
}

Bloquer / Débloquer une carte

Utilisez /blockdigital pour bloquer ou /unblockdigital pour débloquer une carte.

Endpoint: POST /blockdigital ou /unblockdigital

curl -X POST https://magowallet.com/api/visa/blockdigital
-H "Content-Type: application/json" 
-H "publickey: YOUR_PUBLIC_KEY" 
-H "secretkey: YOUR_SECRET_KEY" 
-H "Idempotency-Key: UNIQUE_REQUEST_KEY" 
-d '{
  "cardid": "card_01m0evv599d37vm6dgb0rhd000",
  "email": "jane.doe@example.com"
}'

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

Transactions de carte

Récupère les transactions de la carte. pageNum commence à 1.

Endpoint: POST /transactions

curl -X POST https://magowallet.com/api/visa/transactions
-H "Content-Type: application/json" 
-H "publickey: YOUR_PUBLIC_KEY" 
-H "secretkey: YOUR_SECRET_KEY" 
-d '{
  "cardid": "card_01m0evv599d37vm6dgb0rhd000",
  "pageNum": 1
}'

{
  "cardid": "card_01m0evv599d37vm6dgb0rhd000",
  "pageNum": 1
}

Consulter le code 3DS

Recupere le dernier evenement 3DS disponible pour une carte appartenant au compte API.

Endpoint: POST /check3ds

curl -X POST https://magowallet.com/api/visa/check3ds
-H "Content-Type: application/json" 
-H "publickey: YOUR_PUBLIC_KEY" 
-H "secretkey: YOUR_SECRET_KEY" 
-d '{
  "email": "jane.doe@example.com",
  "cardid": "card_01m0evv599d37vm6dgb0rhd000"
}'

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

Approuver une verification 3DS

Soumet un evenement 3DS recu pour la carte. PagoCards effectue automatiquement la soumission pour approbation.

Endpoint: POST /approve3ds

curl -X POST https://magowallet.com/api/visa/approve3ds
-H "Content-Type: application/json" 
-H "publickey: YOUR_PUBLIC_KEY" 
-H "secretkey: YOUR_SECRET_KEY" 
-H "Idempotency-Key: UNIQUE_REQUEST_KEY" 
-d '{
  "email": "jane.doe@example.com",
  "cardid": "card_01m0evv599d37vm6dgb0rhd000",
  "eventId": "977bdaf833a8423186d599cee720cf29"
}'

{
  "email": "jane.doe@example.com",
  "cardid": "card_01m0evv599d37vm6dgb0rhd000",
  "eventId": "977bdaf833a8423186d599cee720cf29"
}

Card Webhooks

Card events are forwarded to the webhook URL configured on your account. Store and deduplicate events using event_id, return a 2xx response promptly, and expect retries or events arriving out of order. Fields without a value are returned as null.

For transactionCreated events, transStatus is the vendor value: 0 initialization, 1 processing, 2 success, and 3 failure.

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,
    "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",
    "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.

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

Normalized webhook event names

• virtualcard.topup.completed
• virtualcard.transaction.authorization
• virtualcard.transaction.settlement
• virtualcard.transaction.refund
• virtualcard.transaction.fee
• virtualcard.authorization.fee
• virtualcard.transaction.card_application
• virtualcard.transaction.cancellation

Reponses d'erreur

Les erreurs fournissent un code stable. Les erreurs de validation contiennent aussi un objet errors.

{
  "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."]
  }
}