Skip to the content.

BaseURL: https://gateway.paybyrd.com/

Minimum TLS version accepted: 1.2

Sample sandbox Api Key: 2970984F-6234-4D59-A340-24A6B0360334

Sample live Api Key: C2AABE41-D296-4969-90F6-554BEB7E0B3D


Step 1 - Create Payment

The first step is calling the below endpoint from your server. That action will create a payment and you will get a result of that paymentId.

Parameters explanation :

APIKey - The Api Key that was given to you by a paybyrd representative.

amount - Total amount to be charged to your shopper

currency - Valid ISO-4217 alpha code e.g EUR.

orderRef - Your internal reference of the order

The below parameters are only mandatory if Multibanco payment method is activated.

shopperIp - The IP address of your customer/shopper.

shopperFirstName - The first name of your customer/shopper

shopperLastName - The last name of your customer/shopper.

Response explanation :

paymentId - This is the paybyrd payment identifier. You need to keep it so you can use it later

apiKey - The Api Key sent.

type - “HostedForm”.

amount - The total amount sent.

currency - The currency sent.

orderRef - The order sent.

code - Return code from paybyrd API.

description - Return message from paybyrd API.

POST api/v1/createPayment

Request Headers

Content-Type: text/json

Body:

{
  "apiKey": "2970984F-6234-4D59-A340-24A6B0360334",
  "payment": {
     "type": "HostedForm",
     "amount": "100.50",
     "currency": "EUR",
     "orderRef": "ABC123",
     "shopperIp": "82.141.10.5",
     "shopperFirstName": "Jane",
     "shopperLastName": "Jones",
  }
}

Response sample:

{
  "apiKey": "2970984F-6234-4D59-A340-24A6B0360334",
  "payment": {
     "paymentId": "0da33326-1793-4e44-8b35-185ca79ba33b",  
     "type": "HostedForm",
     "amount": "100.50",
     "currency": "EUR",
     "orderRef": "ABC123",
     "shopperIp": "82.141.10.5",
     "shopperFirstName": "Jane",
     "shopperLastName": "Jones",
  },
  "code": "BYRD200",
  "description": "Operation successfully completed"
}

Step 2 - 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.

{
  <form target="myIframe" id="myForm" action="https://gateway.paybyrd.com/v1/hostedform" method="post">
    <input type="hidden" name="paymentid" value="335C879C-31D7-4CB9-B892-7314013797EB"/>
    <input type="hidden" name="redirectUrl" value="https://your-shop.com/success.html"/>
    <input type="hidden" name="culture" value="pt-PT" />
  </form>
  <iFrame style="height:100%;width:100%" name="myIframe" id="myIframe"></iFrame>
}

The above form then should be called :

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

Optional Step 3 - Getting Payment events

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 data 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.

Paybyrd can implement different type of webhooks according to your specific needs. The default implementation is usually just an endpoint on your server that accepts a POST request:

POST https://your-shop.com/paybyrd

Body:

{
  paymentId:"335C879C-31D7-4CB9-B892-7314013797EB"
}

When a payment is completed, failed or gets any update that might be relevant to you, we will call your server to notify you of that. We will send you the paymentId value so that you can query paybyrd afterwards.

You can setup your Webhook Url on Paybyrd using the following method:

PUT api/v1/webhook

Request Headers

Content-Type:text/json

Body sample:

{
  apiKey: "2970984F-6234-4D59-A340-24A6B0360334",
  url:"https://your-shop.com/paybyrd"
}

Step 4 - Checking payment status

The last step about a payment is getting the actual result of that same payment.

Body Parameters explanation:

apiKey - The Api Key that was given to you by a paybyrd representative.

paymentId - This is the paybyrd payment identifier. Previously obtained on step 1 or 3.

POST api/v1/paymentStatus

Request Headers

Content-Type:text/json

Body sample:

{
  apiKey: "2970984F-6234-4D59-A340-24A6B0360334",
  paymentId:"335C879C-31D7-4CB9-B892-7314013797EB"
}

Response sample:

{
  code:"BYRD206",
  description : "Payment successfully completed."
}

Apendix - Testing Card

Testing Card

Card Number - 4200000000000000

Card Holder - Jane Jones

Card Expiry - 05/20

Card CVV - 123


Apendix - Server Messages

The below messages are the most significant for the hosted form integration. For additional messages or extended features please contact a Paybyrd representative.

BYRD101 - Api Key invalid or not found.

BYRD102 - Amount is invalid or empty.

BYRD103 - RedirectUrl is invalid or empty.

BYRD104 - Currency not allowed or not found.

BYRD105 - No brands currently active.

BYRD106 - PaymentId is not valid or had already expired.

BYRD107 - Brand not allowed.

BYRD108 - Card number is invalid or empty.

BYRD109 - Card expire date is invalid or empty.

BYRD110 - Card name is invalid or empty.

BYRD201 - Payment step 1 initiated.

BYRD202 - Payment not yet started. Waiting for shopper.

BYRD203 - Payment attempt rejected.

BYRD204 - Payment processing.

BYRD205 - Payment rejected.

BYRD206 - Payment successfully completed.

BYRD207 - Pending merchant action.

BYRD208 - Payment canceled by the shopper

BYRD301 - Webhook Url is invalid or empty

BYRD401 - Gateway communication error