> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/codapay/hosted-component-integration/cards/saving-card-details.md). # 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:
FieldTypeDescription
enableSavePaymentMethodBooleanEnables the option for users to save their card
displaySavedPaymentMethodListBooleanDisplays previously saved cards to the user
userInitiatedBooleanIndicates whether the user is present in the payment flow
shopperObjectIdentifies 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](/codapay/hosted-payment-page-integration/initiate-a-payment-request.md#request-parameters). 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](#id-1.-first-time-user-save-card-option) 2. [Returning User – Show Saved Cards](#id-2.-returning-user-show-saved-cards) 3. [Returning User – Charge Saved Card Without UI](#id-3.-returning-user-charge-saved-card-without-ui) 4. [Merchant-Initiated Payment – User Not Present](#id-4.-merchant-initiated-payment-user-not-present) #### 1. First-Time User – Save Card Option Allow the user to save their card during checkout.
**Request** ```json { "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": "test@example.com" } ] } } } ``` **Response** ```json { "initResult": { "resultCode": 0, "txnId": 7503012627171645973 } } ``` **Merchant Notification** ```json { "eventType": "PAYMENT_METHOD_ADDED", "timestamp": "2025-06-19T02:48:39.568907Z", "shopper": { "id": "shp_sg197861636b40021", "partner_shopper_id": "test_partner_123_Id", "email": "test@example.com" }, "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** ```json { "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** ```json { "initResult": { "resultCode": 0, "txnId": 7503016855911597963 } } ``` #### 3. \[Coming Soon] Returning User – Charge Saved Card Without UI **Request** ```json { "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** ```json { "initResult": { "resultCode": 0, "txnId": 7503016855911597963 } } ``` #### 4. \[Coming Soon] Merchant-Initiated Payment – User Not Present **Request** ```json { "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** ```json { "initResult": { "resultCode": 0, "txnId": 7503016855911597963 } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coda.co/codapay/hosted-component-integration/cards/saving-card-details.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.