Integration Guide

Maplerad's Issuing is a powerful modern card issuing infrastructure that empowers innovators to change the world. You can instantly issue virtual cards to a customer in different currencies with pricing built to supercharge businesses of all sizes. You always know what you’ll pay.

Let's create a card

To create a card simply follow these steps:

Step 1 -> Create a customer

Step 2 -> Upgrade Customer (Tier 1)

Finally -> Create a Card

*Use Enroll Customer (Full) to avoid Step 1 and 2

Where can the cards be used?

The Maplerad Virtual USD cards are accepted at all merchant sites where USD cards are accepted, they are mostly US merchants like Meta (Facebook), PayPal, Google, Snap inc, Canva and many more. If you encounter any issues please reach out to us at [email protected].

However, there are several merchant sites where the cards may be rejected. They are denoted using a category code known as MCC - Merchant Category Code

The following MCCs denote merchants where Maplerad Virtual USD cards will be rejected.

Webhook

These are example webhook responses for the issuing product

{
  "event": "issuing.transaction",
  "amount": 80,
  "approval_code": null,
  "authorization_amount": 76000,
  "authorization_currency": "NGN",
  "card_acceptor_mcc": "5818",
  "card_acceptor_mid": "3057DL020000002",
  "card_acceptor_state": "",
  "card_id": "7b231d95-9006-4e53-a08c-dbe3b4d3ab4d",
  "created_at": "2023-12-11 21:22:32.312347102 +0000 UTC m=+1129.482495385",
  "currency": "USD",
  "description": "Approved or completed successfully",
  "fee": 0,
  "merchant": {
    "city": "Lagos ",
    "country": "NG",
    "name": "DLO*GOOGLE TikTok Liv"
  },
  "is_termination": false,
  "mode": "DEBIT",
  "reference": "dd7412f3-aa14-4a77-94b5-a26f3cfb-56c",
  "settled": false,
  "status": "SUCCESS",
  "type": "AUTHORIZATION",
  "updated_at": "2023-12-11 21:22:32.312350944 +0000 UTC m=+1129.482499306"
}

{
  "event": "issuing.created.successful",
  "reference": "xxxx", // tracking reference we returned on create endpoint
  "card": {
    "id": "fe796aef-5dca-47d5-a542-16d403b464d1",
    "name": "JOHN DOE",
    "masked_pan": "536898******1914",
    "type": "VIRTUAL",
    "issuer": "VISA",
    "currency": "USD",
    "status": "ACTIVE", // ACTIVE || DISABLED. Active by default
    "balance": 0,
    "auto_approve": true
  }
}

{
  "event": "issuing.created.failed",
  "reference": "xxxx"  // tracking reference we returned on create card endpoint
}

{
  "event": "issuing.terminated",
  "amount": 120, // $1.20
  "card_id": "700865ae-af75-4b6b-b09d-1ecb16753dee",
  "reason": "Insufficient Funds",
  "reference": "61a85f53-6e67-434d-9b6d-fa1d4c7c2f68"
}

{
  "amount": 30,
  "card_id": "32244f-3ac0-431d-9fb0-43f72505",
  "event": "issuing.charge",
  "transaction_date": "2024-12-17 09:26:42.243416144 +0000 UTC"
}

These are the possible transaction types:

• AUTHORIZATION: This is when a card is successfully used at a merchant site.
• AUTHORIZATION-SETTLEMENT: This is when a card is successfully used and settlement is completed at a merchant site.
• FUNDING: This is when a customer funds the card via the /funding endpoint.
• WITHDRAWAL: This is when a customer withdraws from the card via the /withdrawal endpoint.
• TERMINATION: This is when a card is terminated (available on the dashboard).
• DECLINE: When an attempt to use the card at a merchant site is rejected for any reason e.g Insufficient balance.
• REVERSAL: When a merchant charges a card but immediately returns said sum to the card.
• REFUND: This is common when a reversal fails to deliver as expected and a request to get back the funds erroneously debited is made and processed.
• CROSS-BORDER: This transaction is used to identify card cross-border charges. When a card is used on a merchant site that is not based in the US or the authorization currency is not USD.

Mode can only be CREDIT or DEBIT