Lookup payment options

curl --request POST \
  --url https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '{}'

import requests

url = "https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup"

payload = {}
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-idempotency-key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
};

fetch('https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-idempotency-key: <x-idempotency-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup"

	payload := strings.NewReader("{}")

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

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

HttpResponse<String> response = Unirest.post("https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup")

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

request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

{
  "name": "lookup",
  "actionId": "1aa0ef20-36cb-4485-b60e-0526c3699014",
  "executedAt": "2022-02-03T14:38:40.557Z",
  "data": {
    "paymentCompositionOptions": [
      {
        "paymentMethodCode": "card",
        "integrationType": "api",
        "description": "Card.",
        "paymentInstruments": [
          {
            "id": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
            "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
            "createdAt": "2022-04-22T17:53:36.814Z",
            "updatedAt": "2022-04-22T17:53:36.814Z",
            "paymentMethod": "card",
            "displayName": "Visa **** 1111",
            "description": "Personal card.",
            "merchantReference": "ref_C47C47",
            "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
            "status": "created",
            "futureUsage": "CardOnFile",
            "networkTransactionReference": "987654321234567",
            "data": {
              "network": "visa",
              "bin": "411111",
              "suffix": "1111",
              "expiryMonth": "10",
              "expiryYear": "2026",
              "holderName": "John Doe",
              "billingAddress": {
                "country": {
                  "code": "DE",
                  "name": "Germany"
                },
                "postalCode": "10117"
              }
            }
          }
        ],
        "clientConfig": {
          "displayName": "Card",
          "supportsSaveInstrument": true,
          "flow": "direct"
        }
      },
      {
        "paymentMethodCode": "bankAccount",
        "integrationType": "api",
        "description": "Bank Account.",
        "paymentInstruments": [
          {
            "id": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
            "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
            "createdAt": "2022-04-22T17:53:36.814Z",
            "updatedAt": "2022-04-22T17:53:36.814Z",
            "paymentMethod": "bankAccount",
            "description": "Personal bank account.",
            "merchantReference": "ref_C47C47",
            "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
            "status": "created",
            "data": {
              "holder": {
                "firstName": "John",
                "lastName": "Doe",
                "companyName": "ABC Corp",
                "address": {
                  "streetName": "Example St",
                  "streetNumber": "123",
                  "postalCode": "12345",
                  "city": "Anytown",
                  "stateOrProvince": "CA",
                  "country": "US"
                },
                "email": "john.doe@example.com",
                "dob": "1990-01-15",
                "country": {
                  "code": "US",
                  "name": "United States"
                },
                "city": "New York",
                "type": "personal"
              },
              "bank": {
                "name": "Example Bank",
                "branchCode": "1234",
                "code": "56789",
                "address": {
                  "streetName": "Bank St",
                  "streetNumber": "5",
                  "postalCode": "98765",
                  "city": "Banktown",
                  "stateOrProvince": "NY",
                  "country": "US"
                },
                "swiftCode": "EXABUS33XXX",
                "country": {
                  "code": "US",
                  "name": "United States"
                }
              },
              "account": {
                "number": "1234567890",
                "iban": "US123456789012345678901234567890",
                "currency": "USD",
                "type": "savings"
              }
            }
          }
        ],
        "clientConfig": {
          "displayName": "Bank Account",
          "supportsSaveInstrument": true,
          "flow": "direct",
          "instrumentDataSchema": {
            "id": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
            "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
            "createdAt": "2022-04-22T17:53:36.814Z",
            "updatedAt": "2022-04-22T17:53:36.814Z",
            "paymentMethod": "bankAccount",
            "description": "Personal bank account.",
            "merchantReference": "ref_C47C47",
            "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
            "status": "created",
            "data": {
              "holder": {
                "firstName": "John",
                "lastName": "Doe",
                "companyName": "ABC Corp",
                "address": {
                  "streetName": "Example St",
                  "streetNumber": "123",
                  "postalCode": "12345",
                  "city": "Anytown",
                  "stateOrProvince": "CA",
                  "country": "US"
                },
                "email": "john.doe@example.com",
                "dob": "1990-01-15",
                "country": {
                  "code": "US",
                  "name": "United States"
                },
                "city": "New York",
                "type": "personal"
              },
              "bank": {
                "name": "Example Bank",
                "branchCode": "1234",
                "code": "56789",
                "address": {
                  "streetName": "Bank St",
                  "streetNumber": "5",
                  "postalCode": "98765",
                  "city": "Banktown",
                  "stateOrProvince": "NY",
                  "country": "US"
                },
                "swiftCode": "EXABUS33XXX",
                "country": {
                  "code": "US",
                  "name": "United States"
                }
              },
              "account": {
                "number": "1234567890",
                "iban": "US123456789012345678901234567890",
                "currency": "USD",
                "type": "savings"
              }
            }
          }
        }
      }
    ]
  },
  "links": {
    "execution": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016",
    "authorize": {
      "method": "POST",
      "href": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016/authorize"
    }
  }
}

POST

https://api.staging.payrails.io

merchant

workflows

{workflowCode}

executions

{executionId}

lookup

Lookup payment options

curl --request POST \
  --url https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '{}'

import requests

url = "https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup"

payload = {}
headers = {
    "x-idempotency-key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-idempotency-key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
};

fetch('https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-idempotency-key: <x-idempotency-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup"

	payload := strings.NewReader("{}")

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

	req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

HttpResponse<String> response = Unirest.post("https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup")
  .header("x-idempotency-key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.staging.payrails.io/merchant/workflows/{workflowCode}/executions/{executionId}/lookup")

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

request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

{
  "name": "lookup",
  "actionId": "1aa0ef20-36cb-4485-b60e-0526c3699014",
  "executedAt": "2022-02-03T14:38:40.557Z",
  "data": {
    "paymentCompositionOptions": [
      {
        "paymentMethodCode": "card",
        "integrationType": "api",
        "description": "Card.",
        "paymentInstruments": [
          {
            "id": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
            "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
            "createdAt": "2022-04-22T17:53:36.814Z",
            "updatedAt": "2022-04-22T17:53:36.814Z",
            "paymentMethod": "card",
            "displayName": "Visa **** 1111",
            "description": "Personal card.",
            "merchantReference": "ref_C47C47",
            "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
            "status": "created",
            "futureUsage": "CardOnFile",
            "networkTransactionReference": "987654321234567",
            "data": {
              "network": "visa",
              "bin": "411111",
              "suffix": "1111",
              "expiryMonth": "10",
              "expiryYear": "2026",
              "holderName": "John Doe",
              "billingAddress": {
                "country": {
                  "code": "DE",
                  "name": "Germany"
                },
                "postalCode": "10117"
              }
            }
          }
        ],
        "clientConfig": {
          "displayName": "Card",
          "supportsSaveInstrument": true,
          "flow": "direct"
        }
      },
      {
        "paymentMethodCode": "bankAccount",
        "integrationType": "api",
        "description": "Bank Account.",
        "paymentInstruments": [
          {
            "id": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
            "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
            "createdAt": "2022-04-22T17:53:36.814Z",
            "updatedAt": "2022-04-22T17:53:36.814Z",
            "paymentMethod": "bankAccount",
            "description": "Personal bank account.",
            "merchantReference": "ref_C47C47",
            "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
            "status": "created",
            "data": {
              "holder": {
                "firstName": "John",
                "lastName": "Doe",
                "companyName": "ABC Corp",
                "address": {
                  "streetName": "Example St",
                  "streetNumber": "123",
                  "postalCode": "12345",
                  "city": "Anytown",
                  "stateOrProvince": "CA",
                  "country": "US"
                },
                "email": "john.doe@example.com",
                "dob": "1990-01-15",
                "country": {
                  "code": "US",
                  "name": "United States"
                },
                "city": "New York",
                "type": "personal"
              },
              "bank": {
                "name": "Example Bank",
                "branchCode": "1234",
                "code": "56789",
                "address": {
                  "streetName": "Bank St",
                  "streetNumber": "5",
                  "postalCode": "98765",
                  "city": "Banktown",
                  "stateOrProvince": "NY",
                  "country": "US"
                },
                "swiftCode": "EXABUS33XXX",
                "country": {
                  "code": "US",
                  "name": "United States"
                }
              },
              "account": {
                "number": "1234567890",
                "iban": "US123456789012345678901234567890",
                "currency": "USD",
                "type": "savings"
              }
            }
          }
        ],
        "clientConfig": {
          "displayName": "Bank Account",
          "supportsSaveInstrument": true,
          "flow": "direct",
          "instrumentDataSchema": {
            "id": "b8fe6271-5d71-4d28-b8e8-89e64acc0c49",
            "holderId": "788c7c09-a490-4603-915a-e2a957a6cca1",
            "createdAt": "2022-04-22T17:53:36.814Z",
            "updatedAt": "2022-04-22T17:53:36.814Z",
            "paymentMethod": "bankAccount",
            "description": "Personal bank account.",
            "merchantReference": "ref_C47C47",
            "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
            "status": "created",
            "data": {
              "holder": {
                "firstName": "John",
                "lastName": "Doe",
                "companyName": "ABC Corp",
                "address": {
                  "streetName": "Example St",
                  "streetNumber": "123",
                  "postalCode": "12345",
                  "city": "Anytown",
                  "stateOrProvince": "CA",
                  "country": "US"
                },
                "email": "john.doe@example.com",
                "dob": "1990-01-15",
                "country": {
                  "code": "US",
                  "name": "United States"
                },
                "city": "New York",
                "type": "personal"
              },
              "bank": {
                "name": "Example Bank",
                "branchCode": "1234",
                "code": "56789",
                "address": {
                  "streetName": "Bank St",
                  "streetNumber": "5",
                  "postalCode": "98765",
                  "city": "Banktown",
                  "stateOrProvince": "NY",
                  "country": "US"
                },
                "swiftCode": "EXABUS33XXX",
                "country": {
                  "code": "US",
                  "name": "United States"
                }
              },
              "account": {
                "number": "1234567890",
                "iban": "US123456789012345678901234567890",
                "currency": "USD",
                "type": "savings"
              }
            }
          }
        }
      }
    ]
  },
  "links": {
    "execution": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016",
    "authorize": {
      "method": "POST",
      "href": "https://api.staging.payrails.io/merchant/workflows/100ade99-ef8d-43de-8a35-4d31dbdb37d0/executions/99e2f33a-2d17-4c98-8242-6bf5a4a08016/authorize"
    }
  }
}

Authorizations

Authorization

string

header

required

You can use an OAuth2 JWT bearer token in the Authorization header of your API requests for supported endpoints: Authorization: Bearer <YOUR_JWT_HERE>. These tokens are valid for 10 minutes and can be requested via the access token endpoint endpoint.

Headers

x-idempotency-key

string<uuid>

required

Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.

Path Parameters

workflowCode

string

required

Path parameter to specify the workflow code. Machine-friendly code of Workflow.

Pattern: ^[a-z][-A-Za-z0-9]*$

executionId

string<uuid>

required

Identifier of the resource in Payrails.

Body

application/json

amount

object

Hide child attributes

amount.value

string

required

Decimal amount of the major currency unit. Can be any precision.

Pattern: [0-9]+(\.[0-9]+)?

Example:

"12.50"

amount.currency

string

required

ISO 3-letter currency code.

Pattern: ^[A-Z]{3}$

Example:

"EUR"

Response

The lookup action was executed.

name

enum<string>

required

Lookup the available payment methods and instruments.

Available options:

lookup

actionId

string<uuid>

required

Unique identifier for this action execution. If its processing is done asynchronously, you will receive a notification with the same actionId.

executedAt

string<date-time>

required

Date and time when execution of the Action was started.

links

object

required

Links to the next possible actions that can be taken.

Hide child attributes

links.execution

required

URL to fetch the current execution state.

links.authorize

URL to authorize the current execution.

links.startPaymentSession

URL to start a payment session.

data

object

required

Lookup action results.

Hide child attributes

data.paymentCompositionOptions

object[]

required

List of Payment Methods and Payment Instruments that can be used to complete the execution.

Hide child attributes

data.paymentCompositionOptions.integrationType

enum<string>

required

Code of the integration type for using the payment method in the provider.

Available options:

api,

hpp,

inperson

data.paymentCompositionOptions.description

string

required

Description of the Payment Method.

data.paymentCompositionOptions.paymentMethodCode

enum<string>

Code of the payment method selected to perform the payment.

Available options:

alexBankMa7fazty,

amazonPay,

applePay,

audi2pay,

alfa,

alipay,

bankTransfer,

card,

2c2p,

capitecPay,

cibSmartWallet,

easypaisa,

etisalatCash,

fawryMobileWallet,

fawryPay,

googlePay,

jazzCash,

mercadoPago,

monoDirectDebit,

nbePhoneCash,

orangeCash,

oPayWallet,

pagaWallet,

payflex,

payjustnow,

payPal,

pix,

konnect,

qnbEWallet,

wafaCashWallet,

weCash,

genericRedirect,

eftPro,

upi,

cashFreeWallet,

paytmMWallet,

netBanking,

meezaWallet,

vodafoneCash,

alipayQRCode,

sepaDirectDebit,

dcb,

bankAccount,

modo,

ach,

payzoneCash,

revolutPay,

lean,

tabby,

boleto,

oxxo,

spei,

promptPay,

qris,

momoVN,

vietQR,

konbini,

touchNGo,

gCash,

maya,

pse,

pagoEfectivo,

napas,

duitNowQR,

grabPay,

shopeePay,

nequi,

picPay,

ovo,

trueMoney,

iDeal,

bancontact,

khipu,

razerGold,

webPay,

smartPix,

venmo,

klarnaPayLater,

klarnaPayNow,

klarnaPayOverTime,

knet,

scalapay,

bizum

data.paymentCompositionOptions.providerCode

string

Provider code for which the payment composition option is available.

data.paymentCompositionOptions.providerData

object

Provider-specific data needed by to use the payment method for a payment.

data.paymentCompositionOptions.paymentInstruments

object[]

List of stored Payment Instruments for this Method that belong to the specified holder. By default, only includes the ones with status Created or Enabled.

Hide child attributes

data.paymentCompositionOptions.paymentInstruments.id

string<uuid>

required

Id of the instrument.

data.paymentCompositionOptions.paymentInstruments.createdAt

string<date-time>

required

Date and time when the Instrument was created in Payrails.

data.paymentCompositionOptions.paymentInstruments.updatedAt

string<date-time>

required

When the Instrument was last updated.

data.paymentCompositionOptions.paymentInstruments.holderId

string<uuid>

required

Unique identifier of the Holder in Payrails.

data.paymentCompositionOptions.paymentInstruments.paymentMethod

enum<string>

required

Represents the payment method type.

Available options:

alexBankMa7fazty,

applePay,

audi2pay,

bankAccount,

card,

2c2p,

vietQR,

cibSmartWallet,

easypaisa,

etisalatCash,

fawryMobileWallet,

fawryPay,

googlePay,

jazzCash,

nbePhoneCash,

orangeCash,

payPal,

qnbEWallet,

weCash,

genericRedirect,

alfa,

konnect,

eftPro,

netBanking,

upi,

cashFreeWallet,

paytmWallet,

phonePe,

iDeal,

bancontact,

klarnaPayLater,

klarnaPayNow,

klarnaPayOverTime,

scalapay

data.paymentCompositionOptions.paymentInstruments.status

enum<string>

required

Status of the instrument.

Available options:

created,

deleted,

enabled,

disabled,

transient

data.paymentCompositionOptions.paymentInstruments.displayName

string

Instrument name suitable for display.

data.paymentCompositionOptions.paymentInstruments.description

string

Description of the instrument.

data.paymentCompositionOptions.paymentInstruments.default

boolean | null

True if this instrument is set as default for the holder.

data.paymentCompositionOptions.paymentInstruments.merchantReference

string

Merchant-provided reference for the instrument.

data.paymentCompositionOptions.paymentInstruments.fingerprint

string

System-wide unique identifier of the Instrument. If two Holders have the same instrument stored, this value will be the same for both, but the instrument and token IDs will be different. Cannot be used for payments, should only be used for analytics and fraud prevention.

data.paymentCompositionOptions.paymentInstruments.futureUsage

enum<string>

Represents the future usage to define the payment flows that the stored instrument will be used for.

Available options:

Subscription,

CardOnFile,

UnscheduledCardOnFile

data.paymentCompositionOptions.paymentInstruments.networkTransactionReference

string

Identifier of the initial payment made with this instrument on the Networks, e.g. Mastercard Trace ID or Visa Transaction ID.

data.paymentCompositionOptions.paymentInstruments.transactionLinkId

string

Mastercard Transaction Link Identifier (TLID) of the transaction series this instrument belongs to. Returned by the card network on the initial cardholder-initiated transaction and required on economically related merchant-initiated transactions, such as recurring payments and installments, when the series spans payment providers.

data.paymentCompositionOptions.paymentInstruments.data

Card · object

Type-specific information about the instrument.

Hide child attributes

data.paymentCompositionOptions.paymentInstruments.data.network

enum<string>

required

Network of the instrument.

Available options:

unspecified,

visa,

visadankort,

mastercard,

amex,

diners,

discover,

unionpay,

unionpayuzcard,

maestro,

maestrobancontact,

hipercard,

jcb,

jcblankapay,

argencard,

aura,

belkart,

bpfuelcard,

cabal,

carnet,

cirrus,

chjonesfuelcard,

uzcard,

codensa,

dankort,

dinacard,

duet,

ebt,

eftpos,

elo,

euroshellfuelcard,

gecapital,

bc,

hrgstore,

humo,

lankapay,

lukoilfuelcard,

bancontact,

meeza,

newday,

mir,

ourocard,

pagobancomat,

paypak,

paypal,

phhfuelcard,

prostir,

rupay,

sbercard,

sodexo,

starrewards,

cencosud,

naranja,

troy,

uatp,

ukfuelcard,

verve,

voyager,

vpay,

wex,

cmi,

atm,

bankcard,

localbrand,

loyalty,

privatelabel,

fuelcard,

redfuelcard,

redliquidfuelcard

data.paymentCompositionOptions.paymentInstruments.data.bin

string

required

First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number).

Required string length: 6 - 8

Example:

"416598"

data.paymentCompositionOptions.paymentInstruments.data.suffix

string

required

Last digits of the Card number.

Required string length: 4

data.paymentCompositionOptions.paymentInstruments.data.preferredScheme

enum<string>

Network of the instrument.

Available options:

unspecified,

visa,

visadankort,

mastercard,

amex,

diners,

discover,

unionpay,

unionpayuzcard,

maestro,

maestrobancontact,

hipercard,

jcb,

jcblankapay,

argencard,

aura,

belkart,

bpfuelcard,

cabal,

carnet,

cirrus,

chjonesfuelcard,

uzcard,

codensa,

dankort,

dinacard,

duet,

ebt,

eftpos,

elo,

euroshellfuelcard,

gecapital,

bc,

hrgstore,

humo,

lankapay,

lukoilfuelcard,

bancontact,

meeza,

newday,

mir,

ourocard,

pagobancomat,

paypak,

paypal,

phhfuelcard,

prostir,

rupay,

sbercard,

sodexo,

starrewards,

cencosud,

naranja,

troy,

uatp,

ukfuelcard,

verve,

voyager,

vpay,

wex,

cmi,

atm,

bankcard,

localbrand,

loyalty,

privatelabel,

fuelcard,

redfuelcard,

redliquidfuelcard

data.paymentCompositionOptions.paymentInstruments.data.binLookup

object

Information about an issuer by the given BIN (or IIN).

Hide child attributes

data.paymentCompositionOptions.paymentInstruments.data.binLookup.bin

string

required

First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number).

Required string length: 6 - 8

Example:

"416598"

data.paymentCompositionOptions.paymentInstruments.data.binLookup.network

enum<string>

Network of the instrument.

Available options:

unspecified,

visa,

visadankort,

mastercard,

amex,

diners,

discover,

unionpay,

unionpayuzcard,

maestro,

maestrobancontact,

hipercard,

jcb,

jcblankapay,

argencard,

aura,

belkart,

bpfuelcard,

cabal,

carnet,

cirrus,

chjonesfuelcard,

uzcard,

codensa,

dankort,

dinacard,

duet,

ebt,

eftpos,

elo,

euroshellfuelcard,

gecapital,

bc,

hrgstore,

humo,

lankapay,

lukoilfuelcard,

bancontact,

meeza,

newday,

mir,

ourocard,

pagobancomat,

paypak,

paypal,

phhfuelcard,

prostir,

rupay,

sbercard,

sodexo,

starrewards,

cencosud,

naranja,

troy,

uatp,

ukfuelcard,

verve,

voyager,

vpay,

wex,

cmi,

atm,

bankcard,

localbrand,

loyalty,

privatelabel,

fuelcard,

redfuelcard,

redliquidfuelcard

data.paymentCompositionOptions.paymentInstruments.data.binLookup.localNetwork

enum<string>

Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact.

Available options:

bancontact,

cartesbancaires,

dankort,

mada

data.paymentCompositionOptions.paymentInstruments.data.binLookup.issuer

string

Name of the bank or institution that issued the card.

data.paymentCompositionOptions.paymentInstruments.data.binLookup.issuerCountry

object

Country of the bank or institution that issued the card.

Hide child attributes

data.paymentCompositionOptions.paymentInstruments.data.binLookup.issuerCountry.code

string

required

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$

data.paymentCompositionOptions.paymentInstruments.data.binLookup.issuerCountry.iso3

string

ISO 3-letter country code. Returned by Payrails, but not interpreted in requests.

Pattern: ^[A-Z]{3}$

data.paymentCompositionOptions.paymentInstruments.data.binLookup.issuerCountry.name

string

The English name of the country. Returned by Payrails, but not interpreted in requests.

data.paymentCompositionOptions.paymentInstruments.data.binLookup.segment

string

Segment of the card, e.g. gold, black, business.

data.paymentCompositionOptions.paymentInstruments.data.binLookup.type

string

Type of the card, e.g. credit, debit, prepaid, gift.

data.paymentCompositionOptions.paymentInstruments.data.binLookup.typeDetails

string

More information about the card type, e.g. personal, commercial.

data.paymentCompositionOptions.paymentInstruments.data.binLookup.isNetworkToken

boolean

Indicates whether the card credential represents a network token rather than a primary account number (PAN).

data.paymentCompositionOptions.paymentInstruments.data.binLookup.isFlexCard

boolean

Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress

object

Billing Address of the instrument.

Hide child attributes

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.street

string

The name of the street of a postal address.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.doorNumber

string

The number on the door, building, or room.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.complement

string

Additional addressing information, 2nd line of postal address.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.area

string

The name of the suburb or area within a city.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.city

string

The name of the city of a postal address.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.postalCode

string

The postal code.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.state

string

The name of the state a postal address is in.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.country

object

The country where the address is in.

Hide child attributes

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.country.code

string

required

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.country.iso3

string

ISO 3-letter country code. Returned by Payrails, but not interpreted in requests.

Pattern: ^[A-Z]{3}$

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.country.name

string

The English name of the country. Returned by Payrails, but not interpreted in requests.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.latitude

number<float>

Latitude of the address in the GPS coordinate system.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.longitude

number<float>

Longitude of the address in the GPS coordinate system.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.phone

object

The phone to contact in the address (can be different that the customer's).

Hide child attributes

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.phone.number

string

required

The local number of the phone, such that countryCode + number can be dialed.

Pattern: ^[0-9]+$

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.phone.countryCode

string

International prefix of the phone, if known separately.

Pattern: ^\+?[0-9]+$

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.alias

string

Name of the address, e.g. home, work.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.name

string

Name of the person to whom the address belongs to.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.lastName

string

Last name of the person to whom the address belongs to.

data.paymentCompositionOptions.paymentInstruments.data.billingAddress.email

string

Email of the person to whom the address belongs to.

data.paymentCompositionOptions.paymentInstruments.data.expiryMonth

string

Expiry month of the Card.

Required string length: 2

data.paymentCompositionOptions.paymentInstruments.data.expiryYear

string

Expiry year of the Card.

Required string length: 4

data.paymentCompositionOptions.paymentInstruments.data.holderName

string

Name of the owner of the Card.

data.paymentCompositionOptions.paymentInstruments.data.taxId

string

Payer-provided tax identification number (e.g. CPF in Brazil) collected on the instrument.

data.paymentCompositionOptions.paymentInstruments.tokens

object[]

List of tokens inside the instrument. Not included by default, includeTokens query parameter must be used.

Hide child attributes

data.paymentCompositionOptions.paymentInstruments.tokens.id

string<uuid>

required

Id of the token in Payrails.

data.paymentCompositionOptions.paymentInstruments.tokens.createdAt

string<date-time>

required

Date and time when the Token was created in Payrails.

data.paymentCompositionOptions.paymentInstruments.tokens.updatedAt

string<date-time>

required

When the Token was last updated.

data.paymentCompositionOptions.paymentInstruments.tokens.instrumentId

string<uuid>

required

Id of the payment instrument the token belongs to.

data.paymentCompositionOptions.paymentInstruments.tokens.status

enum<string>

required

Status of the token.

Available options:

created,

enabled,

disabled,

deleted

data.paymentCompositionOptions.paymentInstruments.tokens.type

enum<string>

required

Type of the token.

Available options:

network,

vault,

psp,

networkOffers,

networkGateway

data.paymentCompositionOptions.paymentInstruments.tokens.providerId

string<uuid>

required

Id of the provider the token belongs to.

data.paymentCompositionOptions.paymentInstruments.tokens.reference

string

required

Unique identifier of the token in the provider's system.

data.paymentCompositionOptions.paymentInstruments.tokens.providerConfigId

string<uuid>

Id of the configuration in the provider the token belongs to.

data.paymentCompositionOptions.paymentInstruments.tokens.meta

object

Any merchant or provider-specific data that should be stored for context in the token.

data.paymentCompositionOptions.clientConfig

object

Contains information related to the payment method and integration type.

Hide child attributes

data.paymentCompositionOptions.clientConfig.displayName

string

The payment method name.

data.paymentCompositionOptions.clientConfig.supportsSaveInstrument

boolean

Returns true if the payment method supports storing a payment instrument.

data.paymentCompositionOptions.clientConfig.supportsBillingInfo

boolean

Returns true if the merchant wants to collect billing information during checkout and if this information is supported by the payment methods.

data.paymentCompositionOptions.clientConfig.flow

string

Enum with values direct and redirect, direct is set only when a payment method does not require redirecting the end user to a provider page to proceed with authorization.

data.paymentCompositionOptions.clientConfig.additionalConfig

object

Specific configuration needed for the payment method.

data.paymentCompositionOptions.clientConfig.instrumentDataSchema

object

Schema for the payment method.

data.paymentCompositionOptions.clientConfig.supportsInstallments

boolean

Returns true if the payment method supports paying in installments.

data.paymentCompositionOptions.clientConfig.installments

object

Installment plans keyed by ISO 3166-1 alpha-2 country. Empty when no plans are available for this card and amount.

Hide child attributes

data.paymentCompositionOptions.clientConfig.installments.{key}

object[]

Hide child attributes

data.paymentCompositionOptions.clientConfig.installments.{key}.count

integer

required

Number of installments. Sent back as installments.count at authorize.

Example:

6

data.paymentCompositionOptions.clientConfig.installments.{key}.amount

number

required

Amount paid per installment.

Example:

20

data.paymentCompositionOptions.clientConfig.installments.{key}.totalAmount

number

Total paid across all installments, including financing cost. May exceed the transaction amount.

Example:

120

data.paymentCompositionOptions.clientConfig.installments.{key}.displayMessage

string

Ready-to-render description of the plan. Always present for live plans.

Example:

"6 cuotas de S/ 20.000,00 (S/ 120.000,00)"

data.paymentCompositionOptions.clientConfig.installments.{key}.installmentRate

number

Financing rate as a percentage. 0 is a genuine interest-free offer; absent means no rate was supplied.

Example:

32.14

data.paymentCompositionOptions.clientConfig.installments.{key}.discountRate

number

Discount as a percentage. Absent and 0 differ, as for installmentRate.

data.paymentCompositionOptions.clientConfig.installments.{key}.recommended

boolean

Marks the plan the provider suggests emphasising.

data.paymentCompositionOptions.clientConfig.installments.{key}.totalAmountIsEstimate

boolean

The card issuer applies the financing cost, so totalAmount is indicative.

data.paymentCompositionOptions.clientConfig.installments.{key}.disclosures

object[]

Financing rates a market requires be displayed, e.g. CFT and TEA. Values keep the provider's formatting.

Hide child attributes

data.paymentCompositionOptions.clientConfig.installments.{key}.disclosures.code

string

required

Name of the rate.

Example:

"CFT"

data.paymentCompositionOptions.clientConfig.installments.{key}.disclosures.value

string

required

Rate as the provider expressed it.

Example:

"169,00%"

data.paymentCompositionOptions.clientConfig.installments.{key}.requires

enum<string>[]

Conditions the plan imposes beyond the normal card flow. Ignore unrecognised values and hide the plan.

Available options:

threeDSecure,

cardVerificationCode

data.paymentCompositionOptions.clientConfig.installments.{key}.planReference

string

Opaque plan handle. Echo it back at authorize when present; never parse or display it.

Example:

{
  "BR": [
    { "count": 2, "amount": 60 },
    { "count": 6, "amount": 20 }
  ]
}

workspaceId

string<uuid>

Unique identifier of a workspace in Payrails.

Last modified on October 7, 2026

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Lookup payment options

Authorizations

Headers

Path Parameters

Body

Response