User Cards

Introduction

Before diving into this section, it’s recommended to first review the Tokenization section for an understanding of how Ottu securely manages user card data. Optionally, you may also want to familiarize yourself with the Checkout SDK for a smoother integration process. With Ottu, managing your customers’ saved cards is straightforward and secure, thanks to our user-friendly API endpoints. These APIs allow you to fetch all saved cards for a customer or delete a specific card. By incorporating this functionality into your system, you’re ensuring a seamless, personalized, and efficient payment experience for your customers.

User Cards API is not available in KSA.

Installation

When integrating the User Saved Cards endpoints into your system, here are the key points you need to be aware of:

1. You will not receive the full card number (PAN) of the user. Instead, you’ll be provided with the last 4 digits of the card number and a token. This token is what you’ll use for executing payments or authorizations

2. If you’re using the Ottu Checkout SDK, customers can delete their saved cards at any point in time. This flexibility gives users more control over their payment information and helps foster trust in your services.

3. When a customer chooses to save their card for payment, the corresponding token will be included in the payload sent to your designated webhook_url. This allows you to retrieve and handle the saved card token as required for your application.

Successful Payment is a Prerequisite: A saved card, represented by a unique token, can only be created after the customer completes a successful payment transaction. This process ensures the validity of the card and enables tokenization. For a detailed guide on how to implement the card-saving feature, please refer to the Implementation Process documentation.

4. Ottu already facilitates the display of saved cards and allows customers to delete their own cards. However, if you wish for a more granular level of control, you can perform these actions yourself using the provided tokens.

Authentication

To access Ottu’s User Saved Cards API, ensure to use the API-Key authentication method.

API Schema Reference

For a more detailed technical understanding and the implementation specifics of these operations, please refer to the OpenAPI schema in the API Schema Reference section below

Fetch Cards

Retrieve a list of saved cards for the customer.

This endpoint retrieves a list of cards saved by the customer. The response includes details such as the card's masked number, card type, and expiration date. By using this endpoint, you can provide the customer with an overview of their saved cards for future payments.

POST/b/pbl/v2/card/

Authorization

SSO BasicAuthbasicAuth

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

type*enum

Choose between sandbox and production. Select sandbox to retrieve cards created for test Payment Gateway MIDs, or production to fetch real cards used in live transactions.

• sandbox - Sandbox
• production - Production

sandboxproduction

customer_id*string

Retrieve cards associated with a specific customer using their unique customer_id.

pg_codesarray of any

Specify the pg_code if you want to retrieve cards for a particular payment gateway, such as credit-card. The pg_code is initialized in the Checkout API when the session_id is created, with each card being associated with a single payment gateway/pg_code.

agreement_idstring

Retrieve the card associated with a specific agreement ID. When this parameter is provided, the resulting array will contain a maximum of one entry, representing the latest card the customer has used for the auto-debit payment associated with the given agreement ID.

Response

200400401403404405415

Body

application/json

brand*nullable string

The card brand (e.g., Visa, Mastercard) associated with the card. Display this information for customer reference.

customer_id*string

The unique identifier for the customer who owns the card

cvv_required*boolean

Specifies if the card requires the submission of a CVV for transactions. A card without CVV requirement can be used for auto-debit or recurring payments.

expiry_month*string

The card's expiration month. Provide this information for transaction processing and validation.

expiry_year*string

The card's expiration year. Provide this information for transaction processing and validation.

is_expired*boolean

A boolean field indicating whether the card has expired. Use this information to determine if the card is valid for transactions and to notify the customer if necessary.

is_preferred*boolean

Indicates if the card is the customer's preferred payment option. Order cards with this attribute set to true at the top of the list for easy access.

name_on_card*nullable string

The cardholder's name as it appears on the card. Display this information for customer verification.

number*nullable string

The masked card number to be displayed, ensuring customer privacy and security while providing essential information.

pg_code*string

The pg_code associated with the card's creation.

token*string

The unique token associated with the card, required for tokenized card payments. Use this value to securely process transactions.

agreements*object

List of agreements associated with this card.

Request

JavaScriptCurl

const response = await fetch('/b/pbl/v2/card/', {
    method: 'POST',
    headers: {
      "Authorization": "basic <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "customer_id": "text",
      "type": "sandbox"
    }),
});
const data = await response.json();

Response

{
  "brand": "text",
  "customer_id": "text",
  "cvv_required": false,
  "expiry_month": "text",
  "expiry_year": "text",
  "is_expired": false,
  "is_preferred": false,
  "name_on_card": "text",
  "number": "text",
  "pg_code": "text",
  "token": "text"
}

Delete Card

Delete a saved card for the customer.

This endpoint allows you to delete a customer's saved card from the system. Provide the unique card identifier to remove the card from the customer's saved cards list. This action can help maintain up-to-date card information and ensure that customers do not accidentally use expired or unwanted cards for payments.

DELETEhttps://<ottu-url>/b/pbl/v2/card/{{token}}

Authorization

SSO BasicAuthbasicAuth

Path parameters

token*string

The unique token associated with the card to be deleted.

Query parameters

Response

204400401403404415

No Content

Request

JavaScriptCurl

const response = await fetch('https://<ottu-url>/b/pbl/v2/card/{{token}}', {
    method: 'DELETE',
    headers: {
      "Authorization": "basic <token>"
    },
});
const data = await response.json();

FAQ

1️Can I offer to the customer the possibility to save a card without making a successful payment?

At present, it is not possible to save a card without the customer making a successful payment. However, we continually work to expand and improve our services, so stay tuned for updates.

2️How can I delete a card?

You have two methods for removing a card. The first one involves utilizing the User Cards API to retrieve the customer's cards and establishing a user interface on your end to display the list of saved cards. Upon a customer's selection of a card for deletion, you can invoke the Delete API for that particular card. Alternatively, you have the option of employing the Ottu Checkout SDK, which adeptly manages these procedures on your behalf.

3️Can I trigger auto-debit payments?

Yes, but only if the customer has agreed, and their card has been enabled for auto-debit. For more details, refer to our Auto-Debit documentation.

4️Does Ottu save the cards within the Ottu system?

No, Ottu doesn’t store the cards internally. We utilize an external vault for storing card details. In most cases, the cards are saved at the Payment Gateway with which the merchant has a contract. This approach further ensures the safety and security of the card details.

What’s Next?

Now that you’re familiar with how to use and manage User Cards within the Ottu system, you might want to expand your knowledge and capabilities by exploring additional features.

1. Checkout SDK: To make your integration even easier and more seamless, consider utilizing the Ottu Checkout SDK. This tool simplifies many aspects of the payment process, including UI implementation and handling specific payment methods like Apple Pay, Google Pay, STC Pay, among others. You can find more details in our Checkout SDK Documentation.

2. Auto-Debit: Interested in recurring payments or charging your customers when they are offline? Our Auto-Debit feature enables you to do just that. You can learn more about setting up and using Auto-Debit in our Auto-Debit Documentation.

Remember, our support team is here to help if you have any questions or need further assistance. Keep exploring, and let’s make your payment process as efficient and user-friendly as possible!