Webhooks Digital Mastercard

PentrraWallet sends real-time webhook notifications to your server whenever a significant event occurs on one of your Digital Mastercards.

Setup

To receive webhooks, provide a publicly accessible HTTPS URL in your developer dashboard under API Settings → Webhook URL.

PentrraWallet will send a POST request to that URL with a JSON body every time an event occurs on a Digital Mastercard issued through your API integration.

Verifying the webhook

Every webhook payload includes two fields you can use to verify the request genuinely comes from PentrraWallet:

Field	Description
`secret_key`	Your secret key, the same key you use to authenticate API requests
`platform`	Always `"PentrraWallet"`

PHP example:

$payload = json_decode(file_get_contents('php://input'), true);

if ($payload['secret_key'] !== YOUR_SECRET_KEY) {
    http_response_code(401);
    exit('Unauthorized');
}

// Process the event

Node.js example:

app.post('/webhook', (req, res) => {
    const payload = req.body;

    if (payload.secret_key !== process.env.SECRET_KEY) {
        return res.status(401).send('Unauthorized');
    }

    res.status(200).send('OK');
});

Always respond with HTTP 200 as quickly as possible. If PentrraWallet does not receive a 200 response, the request is not retried.

Event types

`card.issued`

Sent when a new Digital Mastercard is successfully issued.

{
  "event": "card.issued",
  "card_id": "crd-a1b2c3d4e5f6a7b8",
  "card_type": "mastercard",
  "card_brand": "mastercard",
  "last_four": "4444",
  "status": "active",
  "timestamp": "2026-08-11T13:00:00-04:00",
  "secret_key": "sk_live_xxxxxxxxxxxx",
  "platform": "PentrraWallet"
}

`card.creation.failed`

Sent when a Digital Mastercard creation attempt fails. The refunded amount has already been credited back to your account balance before this webhook is sent. Fixed creation cost is $3.00.

{
  "event": "card.creation.failed",
  "card_id": "crd-a1b2c3d4e5f6a7b8",
  "card_type": "mastercard",
  "reason": "Invalid card holder information",
  "refund_amount": 3.00,
  "timestamp": "2026-08-11T13:00:00-04:00",
  "secret_key": "sk_live_xxxxxxxxxxxx",
  "platform": "PentrraWallet"
}

Note: this event is only sent if we are able to match the failed attempt to your account and a webhook URL is configured on your API key.

`card.payment.declined`

Sent when a payment attempt is declined on a Digital Mastercard. A fixed decline fee is charged automatically, based on your active plan.

{
  "event": "card.payment.declined",
  "card_id": "crd-a1b2c3d4e5f6a7b8",
  "card_type": "mastercard",
  "merchant": "Netflix",
  "amount": 15.99,
  "reason": "Insufficient funds",
  "fee_charged": 0.50,
  "timestamp": "2026-08-11T13:00:00-04:00",
  "secret_key": "sk_live_xxxxxxxxxxxx",
  "platform": "PentrraWallet"
}

`card.terminated`

Sent when a Digital Mastercard is terminated after 3 consecutive declined payments. The card's remaining balance, minus the termination fee, is settled to your account balance automatically (debited if the balance was already negative). Internally the card status becomes cancelled.

{
  "event": "card.terminated",
  "card_id": "crd-a1b2c3d4e5f6a7b8",
  "card_type": "mastercard",
  "card_balance": 12.40,
  "fee_applied": 2.00,
  "net_amount": 10.40,
  "trx_id": "CARDTERMXXXXXXXX",
  "timestamp": "2026-08-11T13:00:00-04:00",
  "secret_key": "sk_live_xxxxxxxxxxxx",
  "platform": "PentrraWallet"
}

`card.payment.success`

Sent when a payment is successfully authorized on a Digital Mastercard.

{
  "event": "card.payment.success",
  "card_id": "crd-a1b2c3d4e5f6a7b8",
  "card_type": "mastercard",
  "merchant": "Amazon",
  "amount": 59.99,
  "currency": "USD",
  "timestamp": "2026-08-11T13:00:00-04:00",
  "secret_key": "sk_live_xxxxxxxxxxxx",
  "platform": "PentrraWallet"
}

`card.funded`

Sent when a Digital Mastercard is successfully funded and the balance is available for use.

{
  "event": "card.funded",
  "card_id": "crd-a1b2c3d4e5f6a7b8",
  "card_type": "mastercard",
  "amount": 25.00,
  "timestamp": "2026-08-11T13:00:00-04:00",
  "secret_key": "sk_live_xxxxxxxxxxxx",
  "platform": "PentrraWallet"
}

`card.topup.failed`

Sent when a Digital Mastercard funding attempt fails. The amount is refunded to your account balance before this webhook is sent.

{
  "event": "card.topup.failed",
  "card_id": "crd-a1b2c3d4e5f6a7b8",
  "card_type": "mastercard",
  "refund_amount": 25.00,
  "timestamp": "2026-08-11T13:00:00-04:00",
  "secret_key": "sk_live_xxxxxxxxxxxx",
  "platform": "PentrraWallet"
}

Note: card_id may be omitted from this event if the original funding transaction could not be matched to a specific card.

`card.otp.code`

Sent when a one-time verification code (OTP) is generated for a Digital Mastercard transaction. Use this code to authorize the transaction on your side.

{
  "event": "card.otp.code",
  "card_id": "crd-a1b2c3d4e5f6a7b8",
  "card_type": "mastercard",
  "authorization_code": "123456",
  "last_four": "4444",
  "reference": "ref-xxxxxxxx",
  "timestamp": "2026-08-11T13:00:00-04:00",
  "secret_key": "sk_live_xxxxxxxxxxxx",
  "platform": "PentrraWallet"
}

Note: this event is only sent if a webhook URL is configured on your API key.

Webhook payload structure

Every webhook payload shares this common structure:

Field	Type	Description
`event`	string	Event type (e.g. `card.payment.success`)
`card_id`	string	The Digital Mastercard this event relates to
`card_type`	string	Always `"mastercard"`
`timestamp`	string	ISO 8601 datetime of the event
`secret_key`	string	Your secret key, used to verify authenticity
`platform`	string	Always `"PentrraWallet"`

Additional fields vary by event type as documented above. Numeric fields (amount, fee_charged, refund_amount, card_balance, fee_applied, net_amount) are sent as JSON numbers, not strings.

Best practices

Respond immediately. Return HTTP 200 as soon as you receive the request, before any processing.
HTTPS only. Your webhook URL must use HTTPS.
Always verify secret_key. Reject any request where secret_key does not match your credentials.

Need help?

Email: [email protected]
WhatsApp: +44 7451 259717