Skip to content

Secure Card on File

Secure Card on File is a Mastercard technology designed to protect card information and store card data in encrypted form.

Making payments with a token received from Mastercard Checkout Solutions

Request

The bePaid system lets you use data received from Mastercard Checkout Solutions in payment and authorization requests.

To complete a payment and get an operation result, follow these steps:

1) Send /transaction/credentials request and then decode the received JWS (checkoutResponseJWS), after that decrypt the value of encryptedPayload. As a result, you will receive a JSON structured as shown in the example:

Example of the decoded response to the credentials request from Mastercard Checkout Solutions with the decrypted value of encryptedPayload parameter 
{
  "checkoutResponseJWS": {
    "jose_header": {
      "iss": "https://mastercard.com",
      "iat": "1741261660",
      "alg": "RS256",
      "jti": "94bffd13-05a8-48ba-9das8-5b32655c20bd",
      "kid": "20230207164613-sandbox-payload-verification-src-mastercard-int"
    },
    "jws_payload": {
      "srcCorrelationId": "4f339be7.93b322d9-410e-4c18-b786-67953c02e46d",
      "srciTransactionId": "0f4678fc-e64a-4aa6-ba7e-1cf08d7e0ce9",
      "encryptedPayload": {
        "payload": {
          "token": {
            "paymentToken": "4242424242424242",
            "tokenExpirationMonth": "01",
            "tokenExpirationYear": "2029"
          },
          "dynamicData": {
            "dynamicDataValue": "ABoAFAjsi9AAEQMCeKAAADFA=="
          }
        }
      },
      "maskedCard": {
        "srcDigitalCardId": "_YdW8-8cQhm2c3V8aHsoKQ000000000000US",
        "panBin": "518600",
        "panLastFour": "9726",
        "digitalCardData": {
          "status": "ACTIVE",
          "presentationName": "Bank",
          "descriptorName": "MasterCard Test Bank",
          "artUri": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/HIGH-MASK-3x.png"
        },
        "panExpirationMonth": "12",
        "panExpirationYear": "2025",
        "maskedBillingAddress": {
          "addressId": "b90ecb38-897d-4f95-ab43-155658918a96",
          "name": "J*** D**",
          "line1": "1** 5** A*****",
          "line2": "F**** 1*",
          "city": "New York City",
          "state": "NY",
          "countryCode": "US",
          "zip": "10011",
          "createTime": "2025-03-04T11:58:03.275Z"
        },
        "dcf": {
          "applicationType": "WEB_BROWSER",
          "uri": "https://stage.src.mastercard.com/pay/",
          "logoUri": "http://mastercard.com/",
          "name": "mastercard"
        },
        "dateOfCardCreated": "2024-06-21T13:44:44.117Z"
      },
      "maskedConsumer": {
        "srcConsumerId": "54f2a842-223f-4212-9fa4-5ff133ef16b6",
        "maskedConsumerIdentity": {
          "identityProvider": "SRC",
          "identityType": "EMAIL_ADDRESS",
          "maskedIdentityValue": "j*****7@dummyemail.com"
        },
        "maskedEmailAddress": "j*****7@dummyemail.com",
        "maskedMobileNumber": {
          "countryCode": "1",
          "phoneNumber": "(***) ***-*895"
        },
        "maskedNationalIdentifier": "*********",
        "countryCode": "US",
        "languageCode": "EN",
        "maskedFirstName": "j***",
        "maskedLastName": "d**",
        "maskedFullName": "j*** d**",
        "dateConsumerAdded": "2025-03-06T11:44:28.176Z"
      },
      "shippingAddressZip": "10011",
      "shippingCountryCode": "US",
      "assuranceData": {
        "verificationData": [
          {
            "verificationType": "CARDHOLDER",
            "verificationEntity": "03",
            "verificationMethod": "01",
            "verificationResults": "03",
            "verificationTimestamp": "1725371879",
            "verificationEvents": [
              "02"
            ]
          }
        ],
        "eci": "06"
      }
    },
    "jws_signature": "eyJraWiOiIxNDkwNjQtc3RnLXNyYy1mcGFuLWVuY3J5…."
  }
}

2) Encode the JSON received in step 1 using Base64 encoding.

3) Construct the token using the following format: $begateway_scof_decrypted_1_0_0$<base64_Mastercard Checkout Solutions Response_here> where <base64_Mastercard Checkout Solutions Response_here> is the Base64-encoded value obtained in step 2.

4) Include the token generated in step 3 as the value of the request.credit_card.token parameter in the payment or authorization request sent to bePaid.

Example of request with a token 
{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"SCOF test transaction",
      "tracking_id":"your_unique_number",
      "credit_card":{
      "token": "$begateway_scof_decrypted_1_0_0$fn5anNvbgp7CiAgInZQYXltZW50RGF0YUlEIjogIjU0ZGYwMTI0NDhlM2E0MTFiM2Y3MTRiZDU2ZDhlYjAyIiwKICAiY3J5cHRvZ3JhbUluZm8iOiB7CiAgICAiY3J5cHRvZ3JhbSI6ICJbRklMVEVSRURdIiwKICAgICJlY2kiOiAiMDciLAogICAgImF0YyI6ICIzMTQwMiIKICB9LAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJsYXN0NCI6ICIwMDQ0IiwKICAgICJwYXltZW50VHlwZSI6IHsKICAgICAgImNhcmRCcmFuZCI6ICJWSVNBIgogICAgfSwKICAgICJwYXltZW50QWNjb3VudFJlZmVyZW5jZSI6ICJWMDAxMDAxMzAyMDMxNTUxMzk0MjQyMDg4Mzk3NCIKICB9LAogICJ0b2tlbkluZm8iOiB7CiAgICAiZW5jVG9rZW5JbmZvIjogImV5SmhiR2NpT2lKQk1qVTJSME5OUzFjaUxDSnBkaUk2SW1wcVUydHlaVmhoVm1Od2NrSmlYMmtpTENKMFlXY2lPaUpvTVZBeVpVaHlRMTh6V1daaWVIUlJNbE5RYWtGM0lpd2laVzVqSWpvaVFUSTFOa2REVFNJc0luUjVjQ0k2SWtwUFUwVWlMQ0pyYVdRaU9pSTNVRTgwVDFoUVZFaEpTMWN6UWpOSk1VZFRUekV6TVdVNU1HVlpjQzFzVUV4dFpYUm1TWEJQYlZsdFZuZGZURFZKSWl3aVkyaGhibTVsYkZObFkzVnlhWFI1UTI5dWRHVjRkQ0k2SWxOSVFWSkZSRjlUUlVOU1JWUWlMQ0pwWVhRaU9pSXhOak13TURZMk5EUTJJbjAuRlktQUFfNjU4Zmh6cWs1dzZqb2xRY1BNXzlKVWZaYTJWLW5kM2NvWmw3US56d3JzRlRPallGTXpDcTgxLmlJZ09ueGZDWTU1bjJlRzZ3cG82ajlVUFlvWEpMYTNINFo5MnVnLkZOR195dUdGbnpfV2lEM0poTFNXU1EiLAogICAgImxhc3Q0IjogIjA4ODciLAogICAgImV4cGlyYXRpb25EYXRlIjogewogICAgICAibW9udGgiOiAiMTIiLAogICAgICAieWVhciI6ICIyMDIyIgogICAgfSwKICAgICJkZWNUb2tlbkluZm8iOiB7CiAgICAgICJ0b2tlbiI6ICI0eHh4eDA4ODciCiAgICB9CiAgfQp9Cn5+fg=="
      }
  }
}

Info

Each payment/authorization request must have a unique token.

Response

The response to the payment request with the Mastercard Checkout Solutions data will be returned synchronously with transaction statuses and fully conforms to payment or authorization transaction responses.

Errors

Response example if the token was submitted in the wrong format 
{
  "status": "error",
  "code": "E.1030",
  "message": "Invalid payment data",
  "friendly_message": "Invalid payment token. Failed to get payment details by the submitted token."
}