Use cases
- How to offer the buyer to register their card
- How to make a card record without a payment
- One-click payment: offer the list of registered cards
- One-click payment: pre-populate the form with a registered card
Each of these use cases is managed directly from the first step of the payment. I.e., from the moment the request is sent Charge/createPayment
.
How to offer the buyer to register their card
If you wish to offer the buyer to record their card, it is necessary to:
- Enter the Buyer's e-mail in the
Charge/createPayment
, - Fill in the Buyer reference (highly recommended, this reference can then be used for one-click payment),
- Send the parameter
formAction : ASK_REGISTER_PAY
.
It is the merchant's responsibility to make sure the buyer reference is unique.
Example of a request:
{
"amount": ...,
"currency": ...,
"orderId": "myOrderId",
"formAction" : "ASK_REGISTER_PAY",
"customer": {
"reference": "cust-25634",
"email": "joh.doe@mail.com"
}
}
When the buyer enters his card in the payment form, if the card is eligible for registration, he will automatically be given the opportunity to register his card by checking the box provided. If the buyer checks the box and the payment is successful, the response will contain the ID of the alias created which can be used to pre-populate the payment form.
How to make a card record without a payment
If you want to register a card without making a payment, you must:
- Call the WS
Charge/createToken
instead ofCharge/createPayment
, - Enter the buyer's e-mail in the request
Charge/createToken
, - Fill in the Buyer reference (highly recommended, this reference can then be used for one-click payment).
In this case, the user will be able to register his card without making a payment. The error management remains the same.
One-click payment: offer the list of registered cards
If you want to offer the list of registered cards, you must:
- Make sure that the cards you record are associated with the buyer reference, i.e. the parameter
customer.reference
. - Populate the parameter
customer.reference
in the Web ServiceCharge/createPayment
. - Set, during the payments, the formAction field toCUSTOMER_WALLETin the request
Charge/createPayment
.
{
"amount": ...,
"currency": ...,
"orderId": "myOrderId",
"formAction": "CUSTOMER_WALLET",
"customer": {
"reference": "cust-25634",
"email": "joh.doe@mail.com"
}
}
If one or more cards have been registered for your company with the buyer reference passed in parameter, then they will be automatically suggested to the buyer in the payment form.
The buyer also has the option to pay with another card. Thanks to the formAction: CUSTOMER_WALLET
parameter, he will be able to register this new card.
One-click payment: pre-populate the form with a registered card
This means that when you record a card, you have retrieved the card's token ID from the SDK response. The token ID is specified in the parameter transaction.paymentMethodToken
.
It is then possible to pass it in the Charge/createPayment
query in the parameter: paymentMethodToken
.
{
"amount": ...,
"currency": ...,
"orderId": "myOrderId",
"paymentMethodToken": "268431681321684321681"
}
The SDK will then display a pre-filled read-only payment form, and the Buyer will simply enter the CVV, if required.