Save customer payment information

Zip Checkout offers a robust, secure, and compliant way to handle sensitive payment information. By leveraging Zip's infrastructure, you can ensure that payment details are stored safely, adhering to PCI-DSS compliance standards without the need for extensive security measures on your own servers.

warning

DO NOT STORE SENSITIVE DATA like full credit card numbers or CVV codes on your servers unless you comply with PCI-DSS requirements.

Always use HTTPS to secure all communications between your customer's browser and your server.

This guide is designed to provide you with comprehensive process for integrating Zip Checkout into your application, enabling a seamless and secure way to store customer payment information.

note

You will need a Zip account to use this feature. Get your account now.

1. Prepare the Customer ID

Before initiating the checkout session, ensure you have a valid Zip Customer ID. This ID will be used to associate the saved payment details with a specific customer in Zip system. If you don't have a customer ID for the user, you may create via Zip Dashboard or via Customers API.

After customer successfully created, it's best to save the Zip Customer ID as reference in your own customers database.

2. Create a Checkout Session with save_card mode

To initiate saving a customer's payment details, create a Checkout Session with the mode set to save_card. This tells Zip Checkout to save the payment information for future transactions.

curl https://api.zip.ph/v2/sessions \
  -u "sk_xyz...:" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "PHP",
    "customer": "cus_0191621d054308189ac79fa3bc20156d",
    "mode": "save_card",
    "cancel_url": "https://example.com/cancel",
    "success_url": "https://example.com/success",
    "payment_method_types": ["card"]
  }'

You need to pass a Customer ID in the payload. This is to identify which customer to attach the payment details.

Only the card payment method type is currently supported for saving payment details.

Custom line_items are NOT allowed in this mode. Php 1.00 Test Charge will be used as line item default for the checkout session. Custom submit_type is NOT allowed in this mode.

Read on to Checkout Sessions API to learn more.

3. Redirect the customer to the Checkout URL

After creating the Checkout Session, redirect your customer to the payment_url provided in the API response. This URL directs the customer to the Zip Checkout payment page.

Checkout will handle the 3DS authentication requirement for initial card payment and saving payment information of the customer.

After customer successfully paid the session, Checkout will save the payment details to the provided Customer ID in setup and refund the Php 1.00 Test Charge to the customer.

4. Handle the Checkout callback redirect

Once the payment process is complete, you'll receive a callback at the success URL specified during the setup. Retrieve the session details using the session_id included in the callback.

https://example.com/success?session_id=cs_385vaGWWfci0

It's recommended to check the status of the session to ensure the payment was successful and direct your customer to the appropriate page.

curl https://api.zip.ph/v2/sessions/cs_385vaGWWfci0 \
  -u "sk_xyz...:" \
  -H "Accept: application/json"

5. Retrieve customer payment details

Use the Customer ID to retrieve the saved payment details of the customer. You can use the Customers API to retrieve the saved payment details.

GET https://api.zip.ph/v2/customers/cus_0191621d054308189ac79fa3bc20156d

{
    "object": "customer",
    "id": "cus_018f629f4e0eb7d724ed239789ab0177",
    "email": "[email protected]",
    "mobile_number": "",
    "description": "Magpie Customer",
    "sources": [
        {
            "object": "source",
            "id": "src_018e04afa110b671c6fb1149d0d7",
            "type": "card",
            "card": {
        ... },
      ... }
    ],
    ...
}

You will use the saved source_id in the customer to charge your customer in the future. Using a saved payment source will NOT REQUIRE the customer to undergo 3DS authentication again.

6. Charge the customer using the saved payment source

To charge the customer using the saved payment source, create a Charge with the source set to the saved source_id.

curl https://api.zip.ph/v2/charges \
  -u "sk_xyz...:" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "PHP",
    "source": "src_018e04afa110b671c6fb1149d0d7",
    "description": "Top-up 500",
    "statement_descriptor": "Zip Shop",
    "capture": true
  }'

Payments initiated via the Charge API will reflect in your Zip Dashboard. You can view the payment status and reasons in case of payment failures.

By following these steps, you can securely save your customers' payment details using Zip Checkout for faster and smoother payment experience in future interactions.