User Cards

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.

Setup

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.

1. 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.

Boost Your Integration

Enhance your integration with User Card APIs by utilizing our Python SDK tailored for user card management operations. This SDK facilitates efficient interaction with APIs that manage customer card details.

Available Package:

• Python SDK: Provides an object-oriented approach to list all cards associated with a customer and delete a customer's card using a token. This SDK encapsulates the complexities of API calls, focusing on efficiency and simplicity. Learn more

• Django SDK: Facilitates the integration of payment methods into Django projects by providing Django-specific tools and utilities that streamline payment processing. Find out more

For successful implementation, comprehending the fundamental concepts and structures documented is essential. This understanding guarantees robust and maintainable integration of the SDK into your projects.

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.

post

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.

Note: if card is created via save_card operation, below details should be considered

1. The amount must be zero for the save card operation.

2. The selected MID(pg_code) must support tokenization to enable the save card operation.

3. Please note that the save card operation is considered successful without any funds being charged.

4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.

5. When the transaction type is save_card, all previously saved cards returned in the sdk_preload_payload should be hidden since the user is saving a new card and does not need to select from existing ones.

Authorizations

SSO_BasicAuthbasicAuthSSO_JWT_Auth

AuthorizationstringRequired

Header parameters

AuthorizationstringRequired

Private API key to be provided in the format Api-Key <key>.

Default: Api-Key 1sxkXhZt.cz1mPFsYtnPG9nsXhCWuEty6RiaxCbZm

Body

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

typestring · enumRequired

Choose between sandbox, production. To retrieve the cards associated to specified environment type.Payment Gateway MIDs, or production to fetch real cards used in live transactions.

• sandbox - Sandbox
• production - Production

Possible values:

customer_idstringRequired

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

agreement_idstringOptional

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.

Responses

200Success

application/json

Represents token details, only if the user pays with a tokenized card, Ottu will include the token details in the response.

brandstring · max: 32 · nullableRequired

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

customer_idstring · max: 36Required

The unique identifier for the customer who owns the card

cvv_requiredbooleanRequired

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_monthstring · max: 2Required

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

expiry_yearstring · max: 2Required

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

is_expiredbooleanRequired

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_preferredbooleanRead-onlyRequired

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_cardstring · max: 64 · nullableRequired

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

numberstring · max: 19 · nullableRequired

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

pg_codestringRequired

The pg_code associated with the card's creation.

pg_namestring · enumRequired

The payment gateway associated with the user's card.

• knet - Knet
• cybersource - CyberSource
• csuc - Cybersource Unified Checkout
• checkoutcom - checkout.com
• migs - MiGS
• dapi - Dapi
• deema - Deema
• burgan - Burgan
• paypal - PayPal
• mpgs - MPGS
• kpay - KPay
• enet - Enet
• omannet - OmanNet
• benefit - Benefit
• benefit_pay - BenefitPay
• blank - Blank
• cbk - CBK
• fss - FSS
• myfatoorah - MyFatoorah
• ngenius - N-Genius
• ifg - IATA Financial Gateway
• ccavenues - Ccavenues
• payu_india - PayU India
• cod - Cash
• amazon_pay - Amazon Pay
• ottu_pg - Ottu PG
• bookeey - Bookeey
• upg - UPG
• bambora - Bambora
• hyperpay - HyperPay
• qpay - Qpay
• smart_pay - SmartPay
• sohar - SoharInternational
• nbo - NBO
• tabby - Tabby
• tamara - Tamara
• hesabe - Hesabe
• rajhi - Alrajhi Bank
• stc_pay - STC Pay
• stcbahrain - STC Bahrain
• urpay - URPay
• beyon_money - BeyonMoney
• upayments - UPayments
• tap - Tap Payments
• fawry - Fawry
• fiserv - Fiserv
• payon - PayOn
• paymob - PayMob
• moyasar - Moyasar

Possible values:

tokenstring · max: 50Required

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

agreementsanyRequired

List of agreements associated with this card.

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

405Error

application/json

415Error

application/json

post

/b/pbl/v2/card/

HTTPcURLJavaScriptPython

POST /b/pbl/v2/card/ HTTP/1.1
Host: sandbox.ottu.net
Authorization: Api-Key 1sxkXhZt.cz1mPFsYtnPG9nsXhCWuEty6RiaxCbZm
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "type": "sandbox",
  "customer_id": "text",
  "pg_codes": [],
  "agreement_id": "text"
}

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

{
  "brand": null,
  "customer_id": "text",
  "cvv_required": true,
  "expiry_month": "text",
  "expiry_year": "text",
  "is_expired": true,
  "is_preferred": true,
  "name_on_card": null,
  "number": null,
  "pg_code": "text",
  "pg_name": "knet",
  "token": "text",
  "agreements": null
}

Delete Card

Delete a saved card for the customer.

delete

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.

Authorizations

SSO_BasicAuthbasicAuthSSO_JWT_Auth

AuthorizationstringRequired

Path parameters

tokenstringRequired

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

Query parameters

customer_idstringRequired

Utilized to retrieve cards associated with a specific customer using their unique customer_id..

typestringRequired

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.

Responses

204

No Content

application/json

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

415Error

application/json

delete

/b/pbl/v2/card/{token}/

HTTPcURLJavaScriptPython

DELETE /b/pbl/v2/card/{token}/?customer_id=text&type=text HTTP/1.1
Host: sandbox.ottu.net
Authorization: Basic username:password
Accept: */*

{}

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!