Using a Card Identifier (Pull)

Using a Card Identifier (Server-to-Server + public endpoint)

The server-to-server method involves using a card identifier as a reference to the card details. In this approach, you provide a card identifier in the cardPayload object during the Sunlight SDK initialization. Sunlight's servers will use this identifier to securely request the actual card details from your server.

This method is ideal when you have a secure way to reference stored card details on your server and prefer to handle the exchange of card information via server-to-server communication. Additionally, this method is well-suited when there is a secure public endpoint available for sending card details in place.

Suggested API Endpoint for Card Details Exchange


In this guide, we'll provide a recommended design for the API endpoint that facilitates the exchange of the card identifier with the actual card details. This API endpoint will be implemented on your server and will be called by Sunlight's server to securely obtain the necessary card information.

API structure

Below is a suggested design for the API endpoint to be implemented on your server. This endpoint allows Sunlight's server to request card information by providing a card identifier.

Endpoint: Get Card Information by Card Identifier

  • Method: GET
  • Path: /card/{card_identifier}
  • Description: Retrieve card information based on the provided card identifier.

Path Parameters:

  • card_identifier (string)
    • Description: Card Provider's external identifier (as used during the SDK initialization).

Query Parameters:

  • chd (array[string])
    • Description: Cardholder Data. Specifies the cardholder data fields to be returned in the response. Available values include: first_name, last_name, middle_name, country, postal_code, state, city, address_1, address_2, email, phone, ssn, passport.


  • 200 OK
    • Description: Successful operation. The response body contains the requested card information
    • Response Example:
        "pan": "1111111824980865",
        "exp_date": "10/29",
        "cvv": "123"
  • 400 Bad Request
    • Description: Invalid request. The request parameters are incorrect or incomplete.
    • Response Example:
        "code": 10,
        "message": "Card not found"

By implementing the suggested API endpoint on your server, you can facilitate the secure exchange of card identifiers with actual card details in a server-to-server integration with Sunlight. This approach allows you to leverage stored card information while maintaining a high level of security and compliance.