Hosted Form

Tokenization on hosted form 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-sideintegration. The main differences are:

• You will not call the api/v2/tokens API to create the token. Instead you will provide the tokenOptionsnode 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