Paybyrd

https://docs.paybyrd.com
Admin
Paybyrd is an omnichannel payments platform providing a unified REST API and developer tools to...
Tokens:214,717
Snippets:994
Trust Score:7.4
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Query transaction with Go

Source: https://docs.paybyrd.com/api-reference/transactions/query

Go example using net/http to GET a transaction. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.paybyrd.com/api/v2/transactions/{transactionId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### 200 Response Body for Setup URL

Source: https://docs.paybyrd.com/api-reference/webhooks/setup-url

Example 200 response body from the setup URL request. Contains the configured webhook URL, a generated webhookUser UUID, and a webhookPassword used for webhook authentication.

```json
{
  "url": "https://your-url.com/webhook",
  "webhookUser": "b73e9449-e1dc-485a-b4c7-19c540e96cd1",
  "webhookPassword": "@bc123"
}
```

--------------------------------

### Successful webhook setup response

Source: https://docs.paybyrd.com/api-reference/webhooks/setup-url

Example success response (HTTP 200) from the webhook setup endpoint. Contains the configured URL, a generated webhookUser UUID, and a webhookPassword for authentication.

```json
200
{
  "url": "https://your-url.com/webhook",
  "webhookUser": "b73e9449-e1dc-485a-b4c7-19c540e96cd1",
  "webhookPassword": "@bc123"
}
```

--------------------------------

### Install Card Collect with yarn

Source: https://docs.paybyrd.com/embed/card-collect

Install the @paybyrd/card-collect package using yarn.

```bash
yarn add @paybyrd/card-collect

```

--------------------------------

### Query transaction with Python requests

Source: https://docs.paybyrd.com/api-reference/transactions/query

Python example using the requests library to GET a transaction. Prints the response text.

```python
import requests

url = "https://gateway.paybyrd.com/api/v2/transactions/{transactionId}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Install Card Collect with npm

Source: https://docs.paybyrd.com/embed/card-collect

Install the @paybyrd/card-collect package using npm.

```bash
npm install @paybyrd/card-collect

```

--------------------------------

### Install @paybyrd/threedsecure-service-js

Source: https://docs.paybyrd.com/advanced/3ds-authentication/sdk-setup

Install the Paybyrd ThreeDSecure SDK using npm or yarn. The SDK is compatible with TypeScript.

```bash
npm i @paybyrd/threedsecure-service-js

```

```bash
yarn add @paybyrd/threedsecure-service-js

```

--------------------------------

### Initialize Paybyrd Payment App with InitiateRequest

Source: https://docs.paybyrd.com/integrations/point-of-sale/payment-sdk-android

Creates an InitiateRequest with service credential email, password, merchant identifier, and forceInit flag. Calls PaybyrdSettingsSDK.createInitializationData to get an intent and starts the activity for result using the initialization request code.

```kotlin
val initRequest = InitiateRequest(
  serviceCredentialEmail,
  serviceCredencialPassword,
  merchantIdentifier,
  forceInit
)

val initData = PaybyrdSettingsSDK.createInitializationData(
  requireContext(),
  initRequest
)

startActivityForResult(initData.intent, PaybyrdSettingsSDK.INITIALIZATION_REQUEST_CODE)

```

--------------------------------

### GET /api/v2/tokens

Source: https://docs.paybyrd.com/api-reference/tokenization/get-token-by-reference

This snippet documents the GET /api/v2/tokens endpoint, including its authentication header, response structure, and example.

```APIDOC
## GET /api/v2/tokens

### Description
Retrieves a token by its custom reference.

### Method
GET

### Endpoint
https://gateway.paybyrd.com/api/v2/tokens

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication.

### Request Example
No request body is required.

### Response
#### Success Response (200)
- **data** (array) - List of token objects.
  - **tokenId** (string) - Unique identifier of the token.
  - **customReference** (string) - Custom reference associated with the token.
  - **alias** (string) - Alias for the token.
  - **brand** (string) - Card brand (e.g., MASTER).
  - **expiration** (string) - Card expiration date in MM/YY format.
  - **maskedCardNumber** (string) - Masked card number.
- **success** (boolean) - Indicates if the request was successful.
- **errorCode** (string) - Error code if any.
- **pagination** (object) - Pagination details.
  - **pageNumber** (integer) - Current page number.
  - **pageSize** (integer) - Number of items per page.
  - **total** (integer) - Total number of items.
  - **totalAvailable** (integer) - Total available items.

#### Response Example
{
  "data": [
    {
      "tokenId": "512f2ebd-0256-423d-9d6f-433606c15f41",
      "customReference": "Wallet123",
      "alias": "MyPersonalCard1",
      "brand": "MASTER",
      "expiration": "12/25",
      "maskedCardNumber": "514968******8886"
    }
  ],
  "success": true,
  "errorCode": "",
  "pagination": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 1,
    "totalAvailable": 0
  }
}
```

--------------------------------

### Operation type example response

Source: https://docs.paybyrd.com/api-reference/api-code-reference

Example JSON response showing the operationType field, returned by Query Transaction (GET /api/v2/transactions/{transactionId}).

```json
{
  "operationType": "Payment",
  "status": "Success",
  "brand": "VISA",
  "transactionId": "8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
  "amount": "5.00"
}
```

--------------------------------

### Brand example response

Source: https://docs.paybyrd.com/api-reference/api-code-reference

Example JSON response showing the brand field, returned by Create Payment (POST /api/v2/payment) and Query Transaction (GET /api/v2/transactions/{transactionId}).

```json
{
  "brand": "VISA",
  "operationType": "Payment",
  "status": "Success",
  "transactionId": "8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
  "amount": "5.00"
}
```

--------------------------------

### List Settlement Files with Net::HTTP (Ruby)

Source: https://docs.paybyrd.com/api-reference/settlement-files/list-settlement-files

Ruby example using Net::HTTP to call the List Settlement Files endpoint. Requires an x-api-key header with a valid API key.

```ruby
require 'uri'
require 'net/http'

url = URI("https://financehub.paybyrd.com/api/v1/SettlementFiles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### 200 response - Gets a webhook settings by its Id

Source: https://docs.paybyrd.com/api-reference/webhooks/gets-a-webhook-settings-by-its-id

Example 200 response for a successful GET request, containing the webhook's id, url, credentials, and events list.

```JSON
{
  "id": "8668e1dc-3f0c-407d-9aff-f5dda1ee8eaf",
  "url": "https://your-url.com/webhook",
  "webhookUser": "b73e9449-e1dc-485a-b4c7-19c540e96cd1",
  "webhookPassword": "@bc123",
  "events": []
}
```

--------------------------------

### Create webhook with Go

Source: https://docs.paybyrd.com/api-reference/webhooks/creates-a-new-webhook-setting

Uses the net/http package to POST the webhook URL with the required headers and prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.paybyrd.com/api/v2/webhooks"

	payload := strings.NewReader("{\n  \"url\": \"https://your-url.com/webhook\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Finish two-step card payment with Go net/http

Source: https://docs.paybyrd.com/api-reference/payments/finish-two-step-card-payment

Go example using net/http to POST card details to the finish two-step card payment endpoint. Requires an API key and transaction ID. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.paybyrd.com/api/v2/payment/{transactionId}/pay"

	payload := strings.NewReader("{\n  \"card\": {\n    \"number\": \"5386134136087954\",\n    \"expiration\": \"03/29\",\n    \"cvv\": \"965\",\n    \"holder\": \"Peter Parker\",\n    \"ThreeDsVersion\": \"V2\",\n    \"Aav\": \"cbd05c44c572458ba7468df0f75c932a\",\n    \"DsTransactionId\": \"a3ad6ed8-c4b0-4cb4-972e-46e86a041ad1\",\n    \"Eci\": \"01\",\n    \"VerificationMethod\": \"ThreeDSecure\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Order status example response

Source: https://docs.paybyrd.com/api-reference/api-code-reference

Example JSON response showing the order status field, returned by Create Order (POST /api/v2/orders) and Query Order (GET /api/v2/orders/{orderId}).

```json
{
  "orderId": "e83aa1a1-152c-439e-af1e-fc4178520807",
  "status": "created",
  "code": "BYRD200",
  "description": "Operation successfully completed"
}
```

--------------------------------

### 200 response for get all webhook settings

Source: https://docs.paybyrd.com/api-reference/webhooks/gets-all-webhook-settings

Example JSON response returned by the GET /api/v2/webhooks endpoint. Contains an array of webhook objects with id, url, webhookUser, webhookPassword, and events fields.

```json
[
  {
    "id": "8668e1dc-3f0c-407d-9aff-f5dda1ee8eaf",
    "url": "https://your-url.com/webhook1",
    "webhookUser": "b73e9449-e1dc-485a-b4c7-19c540e96cd1",
    "webhookPassword": "@bc123",
    "events": []
  },
  {
    "id": "c1532b84-a819-4e7a-986e-63bfb4fb1ecf",
    "url": "https://your-url.com/webhook2",
    "webhookUser": "d75620b6-8f3e-48f3-bb7d-99ffd0dbf135",
    "webhookPassword": "@bc123",
    "events": []
  }
]
```

--------------------------------

### 200 Response for Get Token By Id

Source: https://docs.paybyrd.com/api-reference/tokenization/get-token-by-id

Example JSON response returned when the token is successfully retrieved.

```json
{
  "tokenId": "512f2ebd-0256-423d-9d6f-433606c15f41",
  "customReference": "Wallet123",
  "alias": "MyPersonalCard1",
  "brand": "MASTER",
  "expiration": "12/25",
  "maskedCardNumber": "514968******8886"
}
```

--------------------------------

### Transaction status example response

Source: https://docs.paybyrd.com/api-reference/api-code-reference

Example JSON response showing the status field at the transaction level, returned by Create Payment (POST /api/v2/payment) and Query Transaction (GET /api/v2/transactions/{transactionId}).

```json
{
  "code": "BYRD200",
  "status": "Success",
  "operationType": "Payment",
  "brand": "VISA",
  "transactionId": "8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
  "amount": "5.00"
}
```

--------------------------------

### List Settlement Files with Unirest (Java)

Source: https://docs.paybyrd.com/api-reference/settlement-files/list-settlement-files

Java example using the Unirest HTTP library to call the List Settlement Files endpoint. Requires an x-api-key header with a valid API key.

```java
HttpResponse<String> response = Unirest.get("https://financehub.paybyrd.com/api/v1/SettlementFiles")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### Query Order with Go

Source: https://docs.paybyrd.com/api-reference/orders/query-order

Use this Go program to query an order using the net/http package. Replace {orderId} and <api-key> with your actual values.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.paybyrd.com/api/v2/orders/{orderId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Query transaction with Java Unirest

Source: https://docs.paybyrd.com/api-reference/transactions/query

Java example using Unirest to GET a transaction. Returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://gateway.paybyrd.com/api/v2/transactions/{transactionId}")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### Create Token with Go

Source: https://docs.paybyrd.com/api-reference/tokenization/create-token

Uses the net/http package to send a POST request with a JSON payload. The response body is read and printed. Replace <api-key> with your actual API key.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.paybyrd.com/api/v2/tokens"

	payload := strings.NewReader("{\n  \"Type\": \"Card\",\n  \"CustomReference\": \"Wallet123\",\n  \"Alias\": \"MyShoppingCard\",\n  \"RedirectUrl\": \"http://client.co/3ds/validation?token=123456\",\n  \"Card\": {\n    \"number\": \"5149682323738886\",\n    \"expiration\": \"03/29\",\n    \"cvv\": \"929\",\n    \"holder\": \"Peter Parker\",\n    \"aav\": \"<string>\",\n    \"dsTransactionId\": \"<string>\",\n    \"eci\": \"<string>\",\n    \"xid\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Query transaction with PHP cURL

Source: https://docs.paybyrd.com/api-reference/transactions/query

PHP example using cURL to GET a transaction. Handles errors and prints the response.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://gateway.paybyrd.com/api/v2/transactions/{transactionId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Create Subscription - Success Response

Source: https://docs.paybyrd.com/api-reference/subscription/create

Example response body for a successful subscription creation. Contains the operation status, subscription ID, amount, currency, interval details, and a checkout URL for payment.

```json
{
  "code": "BYRD200",
  "description": "Operation successfully completed",
  "operationStatus": "Success",
  "subscriptionId": "435483a2-78b5-49e3-8f37-cd1c18834e02",
  "isoAmount": 1000,
  "currency": "EUR",
  "orderRef": "AMZ1962",
  "productDescription": "Spider-Man HQ subscription",
  "intervalType": "monthly",
  "interval": 1,
  "startDate": "1962-08-15",
  "endDate": "2082-08-15",
  "timeZone": "Europe/Berlin",
  "checkoutUrl": "https://link.paybyrd.com/sub_Kr6ZKx8uD"
}
```

--------------------------------

### Query transaction with JavaScript fetch

Source: https://docs.paybyrd.com/api-reference/transactions/query

JavaScript example using fetch to GET a transaction. Logs the JSON response or error.

```javascript
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://gateway.paybyrd.com/api/v2/transactions/{transactionId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Create Subscription with Go net/http

Source: https://docs.paybyrd.com/api-reference/subscription/create

Creates a subscription using the PayByrd API v2 with Go's net/http. Replace <api-key> with your actual API key. The response body is printed.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.paybyrd.com/api/v2/subscriptions"

	payload := strings.NewReader("{\n  \"personId\": 10,\n  \"isoAmount\": 1000,\n  \"currency\": \"EUR\",\n  \"orderRef\": \"AMZ1962\",\n  \"productDescription\": \"Spider-Man HQ subscription\",\n  \"intervalType\": \"monthly\",\n  \"interval\": 1,\n  \"startDate\": \"1962-08-15\",\n  \"endDate\": \"2082-08-15\",\n  \"timeZone\": \"Europe/Berlin\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Return codes example response

Source: https://docs.paybyrd.com/api-reference/api-code-reference

Example JSON response showing the code and description fields returned by all payment and transaction endpoints, including Create Payment, Capture, Refund, Release, and Query Transaction.

```json
{
  "code": "BYRD200",
  "description": "Operation successfully completed",
  "transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
  "amount": "10.00"
}
```

--------------------------------

### Query transaction with Ruby Net::HTTP

Source: https://docs.paybyrd.com/api-reference/transactions/query

Ruby example using Net::HTTP to GET a transaction. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://gateway.paybyrd.com/api/v2/transactions/{transactionId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### GET /api/v1/settings

Source: https://docs.paybyrd.com/api-reference/webhooks

Lists all webhook configurations associated with the API key.

```APIDOC
## GET /api/v1/settings

### Description
Lists all webhook configurations associated with the API key.

### Method
GET

### Endpoint
https://webhook.paybyrd.com/api/v1/settings

### Parameters
#### Headers
- **x-api-key** (string) - Required - Your API key for authentication.

### Request Example
bash
curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: {your_api_key}'


### Response
#### Success Response (200)
No response body documented.

```

--------------------------------

### 200 response for GET token by reference

Source: https://docs.paybyrd.com/api-reference/tokenization/get-token-by-reference

Example successful response with status 200. Contains token data including tokenId, customReference, alias, brand, expiration, and maskedCardNumber, along with pagination details.

```json
{
  "data": [
    {
      "tokenId": "512f2ebd-0256-423d-9d6f-433606c15f41",
      "customReference": "Wallet123",
      "alias": "MyPersonalCard1",
      "brand": "MASTER",
      "expiration": "12/25",
      "maskedCardNumber": "514968******8886"
    }
  ],
  "success": true,
  "errorCode": "",
  "pagination": {
    "pageNumber": 1,
    "pageSize": 10,
    "total": 1,
    "totalAvailable": 0
  }
}
```

--------------------------------

### Initiate payment request with PHP

Source: https://docs.paybyrd.com/advanced/3ds-authentication/simplified-setup

Uses file_get_contents with a stream context to POST a card payment to the Paybyrd sandbox API. Requires your API key in the x-api-key header. Prints the result or an error if the request fails.

```php
$apiKey = "{your_api_key}";
$url = "https://gatewaysandbox.paybyrd.com/api/v2/payment";

$data = [
    "type" => "card",
    "isoAmount" => 100,
    "currency" => "EUR",
    "orderRef" => "YOUR_REF_CODE_HERE",
    "redirectUrl" => "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
    "card" => [
        "number" => "5555341244441115",
        "expiration" => "12/30",
        "cvv" => "893",
        "holder" => "Paybyrd"
    ]
];

$options = [
    "http" => [
        "header" => "Content-Type: application/json\r\n" .
                     "x-api-key: $apiKey\r\n",
        "method" => "POST",
        "content" => json_encode($data),
    ],
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);

if ($result === FALSE) {
    die('Error occurred');
}

echo $result;

```
Tokens:
Raw