Hosted form

Paybyrd's hosted form creates a safe checkout page that lets you collect payments and subscriptions easily with minimal effort. It works in multiple devices and abstracts all the complexity of dealing with different payment methods.

Initiating payment

The first step is to call the below endpoint from your server. That action will create a payment and return the generated transaction identifier.

curl --location -g --request POST '{{paybyrd-gateway}}/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
--data '
{
     "amount": "5.00",
     "currency": "EUR",
     "orderRef": "ABC123456",
     "expiresIn": 24,
     "shopper": {
          "firstName": "JHOSH",
          "lastName": "JONES",
          "email": "[email protected]",
          "phoneNumber": "+319999999921"
     },
     "orderOptions": {
          "redirectUrl": "https://your-site-url/payment-finished"
     },
     "paymentOptions": {
          "useSimulated": false,
          "cardOptions": {
               "isPreAuth": false
          }
     }
}
'
{
  "orderDate": "2021-11-18T15:41:02Z",
  "expiresAt": "2021-11-19T15:41:02Z",
  "status": "created",
  "orderId": "81817c1e-f0f9-4f86-9e24-c987c8781168",
  "amount": "5.00",
  "currency": "EUR",
  "orderRef": "ABC123456",
  "shopper": {
    "shopperId": "3bc86fce-1a7f-4e75-97de-b02ccb611bf6",
    "email": "j*****[email protected]",
    "firstName": "J***H",
    "lastName": "J***S",
    "phoneNumber": "+3*********21"
  },
  "orderOptions": {
    "redirectUrl": "https://your-site-url/payment-finished"
  },
  "paymentOptions": {
    "useSimulated": false,
    "cardOptions": {
      "isPreAuth": false
    }
  },
  "terminalOptions": {
    "notifyChanges": false
  },
  "code": "BYRD200",
  "description": "Operation successfully completed"
}

See the full Reference API here

Integrate an iFrame on your application

The second step is about getting the Paybyrd iFrame on your application. The normal way to achieve this is to send the request data as hidden form fields as per the example code provided below. The browser will then automatically encode the request correctly as per the application/x-www-form-urlencoded format.

IFrame example:

<form target="myIframe" id="myForm" action="{{paybyrd-gateway}}/v1/hostedform" method="post">
  <input type="hidden" name="orderId" value="81817c1e-f0f9-4f86-9e24-c987c8781168"/>
  <input type="hidden" name="redirectUrl" value="https://your-shop.com/success.html"/>
  <input type="hidden" name="failureRedirectUrl" value="https://your-shop.com/fail.html"/>
  <input type="hidden" name="culture" value="pt-PT" />
  <input type="hidden" name="showCancelButton" value="false" />
</form>

<iFrame style="height:100%;width:100%" name="myIframe" id="myIframe"></iFrame>

Parameter

Description

Type

Required

orderId

Order identifier generated on the first step.

GUID

Yes

redirectUrl

Url where the customer will be redirected after the payment.

String

No

failureRedirectUrl

Url where the customer will be redirected in case of failure.

String

No

culture

Culture to be used in the hosted form visualization.

String ("en-US")

No

showCancelButton

Indicates whether the HostedForm cancel button will be displayed or not.

Boolean

No

📘

Hint

RedirectUrl and failureRedirectUrl parameters can be configured directly on your subscription.

In order to load the hosted form, the above form then should be called from your page:

<script type = "text/javascript">
    document.getElementById("myForm").submit();
</script>

Receiving payment result

The easiest and safest way for you to know the result of a payment is to configure a webhook on your server.

A webhook is a way for paybyrd to provide you real-time information about your payments. We deliver the data to your server as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient.


What’s Next

See how to set up a webhook