Saving Card Details

Overview

Codapay supports saving card details for returning users to simplify and accelerate checkout. This capability is available on the Hosted Payment Page for eligible merchants and enabled card schemes.

When enabled, users can store their card securely during checkout and reuse it in future transactions.

⚠️ Note: This feature is not currently available for India and Indonesia

Eligibility and Activation

Saved card functionality is only available for merchants who have been explicitly enabled for this feature.

To enable saved card functionality, contact your Codapay account manager or support team.

If a merchant is not enabled, the payment is processed normally but card details are not saved. A warning is returned in the /v2.0/Payment/Component/init.json response in these cases.

User Identification & Shopper Mapping

Users must be logged into your platform before initiating a payment that involves saving or using a saved card.

You are required to pass a partner_shopper_id in the /v2.0/Payment/Component/init.json request. This field represents the unique user ID in your system. It must:

• Uniquely identify a single user

• Remain consistent across all sessions and devices

• Be included in every saved card–related request

When the first saved card is added, Codapay creates a shopper_id and links it to the provided partner_shopper_id. All saved cards are then associated with this shopper_id.

Codapay uses this linkage to:

• Retrieve saved cards in future checkouts

• Attach newly saved cards to the correct user

• Process recurring or merchant initiated payments without additional user input

Integration Overview

To enable saved card functionality on the Hosted Payment Page, include the following fields in your /v2.0/Payment/Component/init.json request:

Field	Type	Description
enableSavePaymentMethod	Boolean	Enables the option for users to save their card
displaySavedPaymentMethodList	Boolean	Displays previously saved cards to the user
userInitiated	Boolean	Indicates whether the user is present in the payment flow
shopper	Object	Identifies the user and passes billing details used for token creation

Shopper Object

The shopper field in the /v2.0/Payment/Component/init.json request is a list of key-value pairs under shopper.entry[].

Each key corresponds to shopper identity or billing information used to retrieve or create a shopper profile and support saved card functionality.

Key	Required	Description
partnerShopperId	Yes*	Unique user ID from your system (case sensitive)
id	No	Codapay-issued shopper_id to retrieve a known shopper
email	No	Shopper’s email address (required to create a new shopper)
phoneNumber	No	Shopper’s phone number
billingFirstName	No	Shopper’s first name (required for billing and shopper creation)
billingLastName	No	Shopper’s last name (required for billing and shopper creation)
billingDocumentType	Conditional	Type of national ID document (e.g., CPF), required in some markets
billingDocumentId	Conditional	Value of the national ID document, paired with documentType
billingAddress	No	Street address
billingCity	No	City name
billingRegion	No	State or province
billingCountry	No	ISO alpha-2 country code (e.g., US)
billingZipCode	No	Postal code

* Required when saving a card for the first time.

• If id is present, Codapay attempts to retrieve the existing shopper linked to that shopper_id.

• If id is not provided, a new shopper is created and linked to the provided partnerShopperId.

• Fields listed here are required in addition to the standard fields documented here.

Refer to the "Scenarios and Examples" section below for request payloads using this structure.

Scenarios and Examples

This section outlines the most common use cases when integrating saved card functionality. Each use case includes the required parameters and sample request format.

1. First-Time User - Save Card Option

2. Returning User – Show Saved Cards

3. Returning User – Charge Saved Card Without UI

4. Merchant-Initiated Payment – User Not Present

1. First-Time User – Save Card Option

Allow the user to save their card during checkout.

Request

{
  "initRequest": {
    "country": 360,
    "payType": 400,
    "apiKey": "",
    "projectId": "31",
    "orderId": "20250611113402",
    "currency": 360,
    "items": [
      {
        "code": "12ds",
        "price": 10000.00,
        "name": "Star Diamond"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    },
    "enableSavePaymentMethod": true,
    "displaySavedPaymentMethodList": true,
    "userInitiated": true,
    "shopper": {
      "entry": [
        {
          "key": "partnerShopperId",
          "value": "test_partner_123_Id"
        },
        {
          "key": "email",
          "value": "[e-mail]"
        }
      ]
    }
  }
}

Response

{
  "initResult": {
    "resultCode": 0,
    "txnId": 7503012627171645973
  }
}

Merchant Notification

{
  "eventType": "PAYMENT_METHOD_ADDED",
  "timestamp": "2025-06-19T02:48:39.568907Z",
  "shopper": {
    "id": "shp_sg197861636b40021",
    "partner_shopper_id": "test_partner_123_Id",
    "email": "[e-mail]"
  },
  "paymentMethod": {
    "id": "pmt_sg1978616a1900024",
    "type": "card",
    "card": {
      "lastFour": "7263",
      "expirationMonth": "04",
      "expirationYear": "2027"
    }
  }
}

2. Returning User – Show Saved Cards

Display previously saved cards to the user for selection.

Request

{
  "initRequest": {
    "country": 360,
    "payType": 400,
    "apiKey": "",
    "projectId": "31",
    "orderId": "20250611113402",
    "currency": 360,
    "items": [
      {
        "code": "12ds",
        "price": 10000.00,
        "name": "Star Diamond"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    },
    "enableSavePaymentMethod": true,
    "displaySavedPaymentMethodList": true,
    "userInitiated": true,
    "shopper": {
      "entry": [
        {
          "key": "id",
          "value": "shp_sg197861636b40021"
        }
      ]
    }
  }
}

Response

{
  "initResult": {
    "resultCode": 0,
    "txnId": 7503016855911597963
  }
}

3. [Coming Soon] Returning User – Charge Saved Card Without UI

Request

{
  "initRequest": {
    "country": 360,
    "payType": 400,
    "apiKey": "",
    "projectId": "31",
    "orderId": "20250611113402",
    "currency": 360,
    "items": [
      {
        "code": "12ds",
        "price": 10000.00,
        "name": "Star Diamond"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    },
    "enableSavePaymentMethod": true,
    "displaySavedPaymentMethodList": false,
    "userInitiated": true,
    "shopper": {
      "entry": [
        {
          "key": "id",
          "value": "shp_sg197861636b40021"
        }
      ]
    }
  }
}

Response

{
  "initResult": {
    "resultCode": 0,
    "txnId": 7503016855911597963
  }
}

4. [Coming Soon] Merchant-Initiated Payment – User Not Present

Request

{
  "initRequest": {
    "country": 360,
    "payType": 400,
    "apiKey": "",
    "projectId": "31",
    "orderId": "20250611113402",
    "currency": 360,
    "items": [
      {
        "code": "12ds",
        "price": 10000.00,
        "name": "Star Diamond"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    },
    "enableSavePaymentMethod": true,
    "displaySavedPaymentMethodList": false,
    "userInitiated": false,
    "shopper": {
      "entry": [
        {
          "key": "id",
          "value": "shp_sg197861636b40021"
        }
      ]
    }
  }
}

Response

{
  "initResult": {
    "resultCode": 0,
    "txnId": 7503016855911597963
  }
}