Hosted Form
If you wish to know more about the hosted form integration, please check | Hosted form |
Tokenization on hosted form client-side
client-side
The hosted form shifts the responsability of dealing with the checkout payment experience to Paybyrd. Tokenization is also available if you use this feature, but it works slightly different from the server-side
integration. The main differences are:
- You will not call the api/v2/tokens API to create the token. Instead you will provide the
tokenOptions
node in the order creation request. - All the payment flow is handled by Paybyrd. We will collect the card data, trigger the 3D Secure authentication and complete the payment.
- A notification will be sent to you when the process is completed.
Create Token
To create a token using our checkout page, first you need to create an order and provide the customReference
field. Paybyrd will respond with the order data and the checkout URL, that leads to our checkout page, where customers will provide the card information. On this page, they will find a checkbox to authorize the tokenization process during the payment.
Once the card holder clicks on pay, we will do the 3DS Auth and then create the payment. As long as the payment is approved, you will receive the webhook with the created token. If you don't receive the webhook, it's possible to query the token from customReference
using the Tokens API.
Here you can find a create order request and response:
curl --location --request POST 'https://gateway.paybyrd.com/api/v2/orders' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
--data-raw '{
"amount": "100.00",
"orderRef": "OrderReference",
"currency": "EUR",
"shopper": {
"email": "[email protected]",
"firstName": "Dear",
"lastName": "Customer",
"phoneCountryCode": 351,
"phoneNumber": "999888777"
},
"orderOptions": {
"redirectUrl": "https://redirect.url"
},
"paymentOptions": {
"tokenOptions": {
"customReference": "custom_wallet_aggregate"
}
},
"code": "order_code",
"description": "order_description"
}'
{
"orderDate": "2022-03-08T18:15:52Z",
"status": "created",
"checkoutUrl": "https://link.paybyrd.com/chk_d1OSV7s2N",
"index": 1,
"transactions": [],
"orderId": "5d46449e-d3d8-41ce-af56-5fb74313beb2",
"amount": "100.00",
"currency": "EUR",
"orderRef": "OrderReference",
"shopper": {
"shopperId": "9de838ff-594a-44eb-baf7-a8dd34ae959d",
"email": "m***********[email protected]",
"firstName": "D**r",
"lastName": "C*****r",
"phoneCountryCode": 3*1,
"phoneNumber": "99*******77",
"shippingType": "Undefined"
},
"orderOptions": {
"redirectUrl": "https://redirect.url",
"culture": "en-US"
},
"paymentOptions": {
"useSimulated": false,
"cardOptions": {
"isPreAuth": false
},
"tokenOptions": {
"customReference": "custom_wallet_aggregate"
}
},
"terminalOptions": {
"notifyChanges": false
},
"code": "BYRD200",
"description": "Operation successfully completed",
"tags": 0,
"checkoutKey": "eyJMaXZlIjpmYWxzZSwiUGVyc29uSWQiOjEwLCJBbW91bnQiOiIxMDAuMDAiLCJDdXJyZW5jeSI6IkVVUiIsIk9yZGVyUmVmIjoiT1JEMTIzIiwiT3JkZXJJZCI6IjVkNDY0NDllLWQzZDgtNDFjZS1hZjU2LTVmYjc0MzEzYmViMiJ9"
}
Use the token
To use a token during the checkout, you will have to create an order providing the customReference
which was created in the previous step.
CustomReference Validation
The customReference is optional in order creation. If informed, make sure that token customReference is equal to order customReference. Otherwise, the payment will fail.
Inside the create response, you will find a checkout URL, that leads to our checkout page, where, as long as the given customReference
has some token related to it, we will try to use it during the payment.
But, for security matters, two-factor authentication will always happen. We will send a code to customer's email and phone number to avoid fraud. Then, we will validate the code and try to create the payment
Two-factor authentication
The two-factor authentication make use of the Time-based One-Time Password
Updated 4 months ago