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.
Updated 4 days ago