Skip to main content

Card Binding: Request examples

This document explains how to bind a payment card to a customer for future use, retrieve details of binded cards, delete a binded card, list all binded cards for a customer, and finally create a payment using a previously binded card.

We provide minimal request examples for both PCI DSS merchants who collect card data directly and non-PCI DSS merchants who rely on a hosted payment page to securely handle card details.

Overview​

A binded card belongs to a specific customer. After a successful payment, the gateway returns a cardId that you can reuse for future payments, so the customer does not have to re-enter their card details. This guide covers:

  1. Binding a card (PCI DSS and non-PCI DSS scenarios)
  2. Checking the order status (or receiving a callback) to get the cardId
  3. Creating an order using a binded card
  4. Retrieving binded card details (optional)
  5. Deleting a binded card (optional)
  6. Listing all binded cards for a customer (optional)
sequenceDiagram
title Card Binding and Subsequent Usage

participant Merchant
participant PG as Payment Gateway

note over Merchant,PG: Step 1 - Create an Order to Bind the Card
Merchant->>PG: Create Order (PCI or Non-PCI)
activate PG
PG->>Merchant: Return order info + (optional) paymentLink
deactivate PG
note over Merchant,PG: Once payment is successful, the card is bound to customerId

note over Merchant,PG: Step 2 - Callback or Check Order Status
PG->>Merchant: Callback or Order Status (completed) + cardId

note over Merchant,PG: Step 3 - Create an Order with the Bound Card
Merchant->>PG: Create Order (entryMode = saved_card) + cardId
activate PG
PG->>Merchant: Return new order info
deactivate PG

opt Retrieve Bound Card Details
    Merchant->>PG: Retrieve card info (cardId, customerId)
    PG->>Merchant: Return masked number, expiry, status
end

opt Delete Bound Card
    Merchant->>PG: Delete bound card (cardId, customerId)
    PG->>Merchant: Return "deleted"
end

opt List All Bound Cards
    Merchant->>PG: List bound cards (customerId)
    PG->>Merchant: Return array of bound cards
end

1. Bind a Card​

To bind a card, you must first create an order that is successfully paid by your customer. Once the payment completes, the card will be binded automatically. The order is created using the Create Order endpoint.

If you are a PCI DSS merchant who collects card data directly, you can choose either approach (PCI DSS or non-PCI DSS). If you are a non-PCI DSS merchant, you must use the “Non-PCI DSS” approach below.

Only this first step differs for PCI DSS vs. non-PCI DSS merchants. All following steps are the same.

In the PCI DSS scenario, you handle card data (PAN, CVV, expiration date, etc.) on your own payment page or server. You must be PCI DSS compliant because you directly process sensitive data.

curl -L 'https://gateway.madfintech.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>' \
--data-raw '{
  "shopId": 1234,
  "order": {
    "orderNumber": "56573FDFVFDBWF",
    "localDateTime": "2023-03-06T14:15:23",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    }
  },
  "customer": {
    "customerId": "56656",
    "saveCard": true
  },
  "paymentSettings": {
    "entryMode": "cnp",
    "instrumentType": "card",
    "providerCode": "someProvider"
  },
  "paymentPageDesign": {
    "format": "shop_hosted"
  },
  "payer": {
    "cardData": {
      "cardNumber": "4111111111111111",
      "cardHolderName": "JOHN A DOE",
      "cvv": "010",
      "expireMonth": "12",
      "expireYear": "2023"
    },
    "personalData": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "billingAddress": {
      "addressLine1": "7, Sunny street",
      "countryCode": "CY"
    }
  }
}'
{
  "data": {
    "orderNumber": "56573FDFVFDBWF"
  }
}

2. Callback or Check Order Status to Get cardId​

After a successful payment, the gateway automatically binds the card to the specified customerId.

When the payment status reaches completed, you receive a callback that includes cardId in data -> payments -> paymentDetails -> cardId. You can store this cardId to reuse it in future transactions.
Alternatively, you can get cardId by calling the order status endpoint once the order is paid.

If the order was not successfully paid, no cardId will be returned.

curl -L 'https://gateway.madfintech.com/api/v1/order/1234/56573FDFVFDBWF' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>'
{
  "data": {
    "id": 54222,
    "shopId": 1234,
    "orderNumber": "56573FDFVFDBWF",
    "orderStatus": "completed",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    },
    "timeLimit": "2023-08-29T15:34:56+03:00",
    "orderCreatedAt": "2023-08-29T15:34:56+03:00",
    "orderPaidAt": "2023-08-29T15:34:56+03:00",
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "79",
        "paymentType": "payment",
        "cost": {
          "amount": "56.99",
          "currency": "USD"
        },
        "acquirer": {
          "code": "someProvider"
        },
        "provider": {
          "code": "someProvider"
        },
        "instrumentType": "card",
        "paymentStatus": {
          "status": "completed"
        },
        "paymentDetails": {
          "paymentSystem": "visa",
          "authCode": "auth94753457343",
          "rrn": "rrn583743856734",
          "maskedCardNumber": "123456******1234",
          "cardId": "c12345"
        },
        "providerPaymentId": "990943",
        "transactionId": "172666307000000001"
      }
    ],
    "customer": {
      "customerId": "56656"
    }
  }
}

3. Create an Order Using a Binded Card​

When you have the cardId of a previously binded card, you can charge it directly (no need for the customer to input details again) by calling the Create Order endpoint.

curl -L 'https://gateway.madfintech.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>' \
--data-raw '{
  "shopId": 1234,
  "order": {
    "orderNumber": "56573FDFVFDBWF2",
    "localDateTime": "2023-03-06T14:15:23",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    }
  },
  "customer": {
    "customerId": "56656"
  },
  "paymentSettings": {
    "entryMode": "saved_card",
    "instrumentType": "card",
    "providerCode": "someProvider"
  },
  "payer": {
    "cardData": {
      "cardId": "c12345"
    }
  }
}'
{
  "data": {
    "orderNumber": "56573FDFVFDBWF2"
  }
}

4. Retrieve Binded Card Details (Optional)​

If you want to see the status or details (masked number, expiry date) of a binded card, call the Retrieve Binded Card Details endpoint.

curl -L 'https://gateway.madfintech.com/api/v1/binded-cards/?cardId=c12345&customerId=56656&shopId=1234' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>'
{
  "cardId": "c12345",
  "maskedCardNumber": "123456******1234",
  "status": "active",
  "customerId": "56656",
  "cardIssuerName": "MyBank",
  "expireMonth": "12",
  "expireYear": "2023"
}

5. Delete a Binded Card (Optional)​

If the customer no longer wants a particular card to remain binded, you can remove it using the Delete a Binded Card endpoint.

curl -L -X DELETE 'https://gateway.madfintech.com/api/v1/binded-cards/?cardId=c12345&customerId=56656&shopId=1234' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>'
{
  "cardId": "c12345",
  "status": "deleted"
}

6. List All Binded Cards for a Customer (Optional)​

To view all binded cards for a specific customer, use the List All Binded Cards for a Customer endpoint.

curl -L 'https://gateway.madfintech.com/api/v1/binded-cards/list?customerId=56656&shopId=1234' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: <Api-Access-Token>'
{
  "data": [
    {
      "cardId": "c12345",
      "maskedCardNumber": "123456******1234",
      "status": "active",
      "customerId": "56656",
      "cardIssuerName": "MyBank",
      "expireMonth": "12",
      "expireYear": "2023"
    }
  ]
}