Meta

{
  "order": {
    "storeId": "store-123",
    "reference": "order_3573894940903",
    "placement": {
      "country": {
        "code": "DE"
      },
      "city": "Berlin"
    },
    "deliveryAddress": {
      "city": "Ankeborg",
      "country": {
        "code": "SE"
      },
      "doorNumber": "1",
      "street": "Stargatan",
      "postalCode": "12345",
      "name": "Peter",
      "lastName": "Parker",
      "email": "notbatman@gmail.com"
    },
    "billingAddress": {
      "city": "Ankeborg",
      "country": {
        "code": "SE"
      },
      "doorNumber": "1",
      "street": "Stargatan",
      "postalCode": "12345",
      "name": "Bruno",
      "lastName": "Diaz",
      "email": "iambatman@gmail.com"
    },
    "lines": [
      {
        "id": "123",
        "quantity": 1,
        "taxPercentage": {
          "value": "5"
        },
        "description": "Delicious Beer.",
        "name": "Beer 1",
        "total": {
          "value": "100",
          "currency": "SEK"
        },
        "links": {
          "productUrl": "https://www.amazingmerchant.com/products/1",
          "imageUrl": "https://www.amazingmerchant.com/products/1.jpeg"
        }
      }
    ]
  },
  "customer": {
    "reference": "1231905323475",
    "name": "FirstName",
    "lastName": "LastName",
    "email": "someone@email.com",
    "type": "VIP",
    "country": {
      "code": "SE"
    }
  },
  "clientContext": {
    "ipAddress": "217.110.239.132",
    "osType": "ios",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "language": "nl_NL",
    "colorDepth": 24,
    "screenHeight": 723,
    "screenWidth": 1536,
    "timeZoneOffset": 0,
    "javaEnabled": true,
    "javaScriptEnabled": true,
    "cookiesAccepted": true,
    "origin": "https://merchant.com/checkout",
    "host": "merchant.com"
  },
  "vendor": {
    "reference": "vendor-123",
    "name": "Cool Restaurant"
  },
  "risk": {
    "score": "80",
    "skipPaymentProviderRules": false,
    "force3DS": true,
    "threeDSMode": "Default",
    "allowNative3DS": true,
    "sessionId": "34567890123",
    "exemptionIndicator": "lowValue"
  },
  "subscription": {
    "chargeFrequency": "P1M",
    "expiration": "2027-12-01",
    "startDate": "2026-12-01",
    "scheduledDate": "2027-01-01",
    "amountType": "variable",
    "minAmount": "300"
  },
  "tags": {
    "customKey": "customValue"
  }
}

Metadata for the context of an execution. Includes Payrails-defined structures for most common fields used in workflows, but can also be extended by merchant or provider-specific fields. For more information, visit our Meta Fields guide.

order

object

The order being placed on your system.

Hide child attributes

order.reference

string

Order reference number sent by the merchant. Defaults to merchantReference in the execution if not specified.

order.description

string

A human-readable name or description of this order.

order.softDescriptor

string

Text that should appear in the bank statement of the customer. Can be requested, but keep in mind that some providers and issuers don't allow you to change this.

order.storeId

string

Order Store ID identifies the particular store associated with this order.

order.placement

object

Data about where the order was placed.

Hide child attributes

order.placement.country

object

Country in which the customer placed the order.

Hide child attributes

order.placement.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

order.placement.country.iso3

string

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

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

order.placement.country.name

string

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

order.placement.city

string

City in which the customer placed the order.

order.deliveryAddress

object

The address the items are to be shipped to.

Hide child attributes

order.deliveryAddress.street

string

The name of the street of a postal address.

order.deliveryAddress.doorNumber

string

The number on the door, building, or room.

order.deliveryAddress.complement

string

Additional addressing information, 2nd line of postal address.

order.deliveryAddress.area

string

The name of the suburb or area within a city.

order.deliveryAddress.city

string

The name of the city of a postal address.

order.deliveryAddress.postalCode

string

The postal code.

order.deliveryAddress.state

string

The name of the state a postal address is in.

order.deliveryAddress.country

object

The country where the address is in.

Hide child attributes

order.deliveryAddress.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

order.deliveryAddress.country.iso3

string

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

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

order.deliveryAddress.country.name

string

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

order.deliveryAddress.latitude

number<float>

Latitude of the address in the GPS coordinate system.

order.deliveryAddress.longitude

number<float>

Longitude of the address in the GPS coordinate system.

order.deliveryAddress.phone

object

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

Hide child attributes

order.deliveryAddress.phone.number

string

required

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

Pattern: ^[0-9]+$

order.deliveryAddress.phone.countryCode

string

International prefix of the phone, if known separately.

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

order.deliveryAddress.alias

string

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

order.deliveryAddress.name

string

Name of the person to whom the address belongs to.

order.deliveryAddress.lastName

string

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

order.deliveryAddress.email

string

Email of the person to whom the address belongs to.

order.deliveryAddressPreference

enum<string>

Determines which Shipping details to use in express payment methods.

Available options:

noShipping,

userPreSpecified,

allowProviderOverride

order.deliveryDate

string<date-time>

When the order is to be delivered.

order.billingAddress

object

The address to put on the bill for this order.

Hide child attributes

order.billingAddress.street

string

The name of the street of a postal address.

order.billingAddress.doorNumber

string

The number on the door, building, or room.

order.billingAddress.complement

string

Additional addressing information, 2nd line of postal address.

order.billingAddress.area

string

The name of the suburb or area within a city.

order.billingAddress.city

string

The name of the city of a postal address.

order.billingAddress.postalCode

string

The postal code.

order.billingAddress.state

string

The name of the state a postal address is in.

order.billingAddress.country

object

The country where the address is in.

Hide child attributes

order.billingAddress.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

order.billingAddress.country.iso3

string

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

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

order.billingAddress.country.name

string

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

order.billingAddress.latitude

number<float>

Latitude of the address in the GPS coordinate system.

order.billingAddress.longitude

number<float>

Longitude of the address in the GPS coordinate system.

order.billingAddress.phone

object

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

Hide child attributes

order.billingAddress.phone.number

string

required

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

Pattern: ^[0-9]+$

order.billingAddress.phone.countryCode

string

International prefix of the phone, if known separately.

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

order.billingAddress.alias

string

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

order.billingAddress.name

string

Name of the person to whom the address belongs to.

order.billingAddress.lastName

string

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

order.billingAddress.email

string

Email of the person to whom the address belongs to.

order.shippingType

enum<string>

The method by which the order is fulfilled:

pickup: The customer picks up the order.
physical: The order is physically delivered.
digital: The order is delivered electronically.
hybrid: A combination of physical and digital fulfillment.

Available options:

pickup,

physical,

hybrid,

digital

order.shipping

object

The shipping total price of the order.

Hide child attributes

order.shipping.value

string

required

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

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

Example:

"12.50"

order.shipping.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.totalDiscount

object

The total discount applied on the order.

Hide child attributes

order.totalDiscount.value

string

required

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

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

Example:

"12.50"

order.totalDiscount.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.totalTax

object

The total taxes for the order.

Hide child attributes

order.totalTax.value

string

required

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

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

Example:

"12.50"

order.totalTax.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.lines

object[]

List of details per item in the order.

Hide child attributes

order.lines.name

string

The name of the item.

order.lines.description

string

The description of the item.

order.lines.product

object

The details of the product item.

Hide child attributes

order.lines.product.type

enum<string>

The type of the product item.

Available options:

physical,

digital,

service

order.lines.categoryId

string

Category identifier of the item on the merchant's system.

order.lines.type

enum<string>

The type of the item. the line value will be added to the order total in case of lineItem, tax and subtracted from order total in case of discount.

Available options:

lineItem,

discount,

tax

order.lines.quantity

integer

How many instances of this item are part of the order.

order.lines.unitPrice

object

How much does a unit of the item cost.

Hide child attributes

order.lines.unitPrice.value

string

required

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

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

Example:

"12.50"

order.lines.unitPrice.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.lines.total

object

Cost of unit price multiplied by quantity with the tax and discount applied.

Hide child attributes

order.lines.total.value

string

required

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

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

Example:

"12.50"

order.lines.total.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.lines.taxPercentage

object

Tax percentage that applies to the specific item, applicable only where item.type == lineItem, will be ignored when not providing item.unitPrice.

Hide child attributes

order.lines.taxPercentage.value

string

required

A percentage value up to 2 decimal precision.

Pattern: ^((100)|(\d{1,2}(\.\d*)?))$

Example:

"12.50"

order.lines.taxCode

enum<string>

Tax code classifying the item for tax calculation.

Available options:

businessSaas,

consumerSaas,

businessSaasSecurity,

consumerSaasSecurity,

businessSaasStorage,

consumerSaasStorage,

softwareOnprem,

businessPaas,

consumerPaas,

businessIaas,

consumerIaas,

businessWebHosting,

consumerWebHosting,

businessDomainNames,

consumerDomainNames,

businessSoftwareDownload,

consumerSoftwareDownload,

businessSoftwareMaintenanceOptional,

consumerSoftwareMaintenanceOptional,

businessDigitalSubscription,

consumerDigitalSubscription,

businessGamingSubscription,

consumerGamingSubscription,

businessVideoSubscription,

consumerVideoSubscription,

businessPhotographySubscription,

consumerPhotographySubscription,

businessMusicSubscription,

consumerMusicSubscription,

businessEbookSubscription,

consumerEbookSubscription,

businessInAppSubscription,

consumerInAppSubscription,

businessDatasetSubscription,

consumerDatasetSubscription,

businessDigitalPermanent,

consumerDigitalPermanent,

businessGamingPermanent,

consumerGamingPermanent,

businessVideoPermanent,

consumerVideoPermanent,

businessPhotographyPermanent,

consumerPhotographyPermanent,

businessMusicPermanent,

consumerMusicPermanent,

businessNft,

consumerNft,

businessEbookPermanent,

consumerEbookPermanent,

businessInAppPermanent,

consumerInAppPermanent,

businessDatasetPermanent,

consumerDatasetPermanent,

businessDigitalAdvertising,

consumerDigitalAdvertising,

exempt

order.lines.servicePeriod

object

The billing period this line covers, for a recurring/subscription charge. Omit for one-time line items.

Hide child attributes

order.lines.servicePeriod.startDate

string<date-time>

required

Start of the billing period this line covers.

order.lines.servicePeriod.endDate

string<date-time>

required

End of the billing period this line covers.

order.lines.totalDiscount

object

The total discount applied on this item (quantity x discount per item), applicable only where item.type == lineItem, will be ignored when not providing item.unitPrice.

Hide child attributes

order.lines.totalDiscount.value

string

required

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

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

Example:

"12.50"

order.lines.totalDiscount.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.lines.totalTax

object

The total tax added for this item (quantity x tax per item), applicable only where items.type = lineItem, will be ignored when not providing item.unitPrice.

Hide child attributes

order.lines.totalTax.value

string

required

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

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

Example:

"12.50"

order.lines.totalTax.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.lines.id

string

Identifier of the item on the merchant's system.

order.lines.brand

string

The manufacturer or brand name of the item.

order.lines.weight

number<float>

The weight of the item, in kilograms.

order.lines.links

object

Relevant links about the item.

Hide child attributes

order.lines.links.productUrl

string

URL of the product information page.

order.lines.links.imageUrl

string

URL of the image of the item.

order.lines.travelTicket

object

Details about the travel ticket.

Hide child attributes

order.lines.travelTicket.ticketId

string

The ID of the travel ticket.

order.lines.travelTicket.type

enum<string>

The mode of transport the travel ticket is for.

Available options:

bus,

air

order.lines.travelTicket.passengers

object[]

The passengers on the travel ticket.

Hide child attributes

order.lines.travelTicket.passengers.name

string

The name of the passenger.

order.lines.travelTicket.passengers.lastName

string

The last name of the passenger.

order.lines.travelTicket.passengers.phone

object

The phone number of the passenger.

Hide child attributes

order.lines.travelTicket.passengers.phone.number

string

required

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

Pattern: ^[0-9]+$

order.lines.travelTicket.passengers.phone.countryCode

string

International prefix of the phone, if known separately.

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

order.lines.travelTicket.passengers.passengerType

enum<string>

The type of the passenger.

Available options:

adult,

child,

infant,

senior

order.lines.travelTicket.passengers.email

string

The email of the passenger.

order.lines.travelTicket.routes

object[]

The routes on the travel ticket.

Hide child attributes

order.lines.travelTicket.routes.legs

object[]

The legs on the route.

Hide child attributes

order.lines.travelTicket.routes.legs.legId

string

The ID of the leg.

order.lines.travelTicket.routes.legs.departure

object

A point on a travel ticket leg.

Hide child attributes

order.lines.travelTicket.routes.legs.departure.city

string

The city of the point.

order.lines.travelTicket.routes.legs.departure.country

object

The country of the point.

Hide child attributes

order.lines.travelTicket.routes.legs.departure.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

order.lines.travelTicket.routes.legs.departure.country.iso3

string

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

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

order.lines.travelTicket.routes.legs.departure.country.name

string

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

order.lines.travelTicket.routes.legs.departure.airportCode

string

The 3-letter IATA airport code of the point, for air legs.

Example:

"AMS"

order.lines.travelTicket.routes.legs.departure.time

string<date-time>

The time of the point.

order.lines.travelTicket.routes.legs.arrival

object

A point on a travel ticket leg.

Hide child attributes

order.lines.travelTicket.routes.legs.arrival.city

string

The city of the point.

order.lines.travelTicket.routes.legs.arrival.country

object

The country of the point.

Hide child attributes

order.lines.travelTicket.routes.legs.arrival.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

order.lines.travelTicket.routes.legs.arrival.country.iso3

string

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

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

order.lines.travelTicket.routes.legs.arrival.country.name

string

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

order.lines.travelTicket.routes.legs.arrival.airportCode

string

The 3-letter IATA airport code of the point, for air legs.

Example:

"AMS"

order.lines.travelTicket.routes.legs.arrival.time

string<date-time>

The time of the point.

order.lines.travelTicket.routes.legs.carrier

object

The company operating the leg.

Hide child attributes

order.lines.travelTicket.routes.legs.carrier.code

string

The 2-letter IATA airline code, for air legs.

Example:

"KL"

order.lines.travelTicket.routes.legs.carrier.name

string

The name of the carrier.

order.total

object

Total order value. Can be different than the execution amount in case discounts or other costs are involved. This value will be ignored if costs are detailed in the lines array.

Hide child attributes

order.total.value

string

required

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

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

Example:

"12.50"

order.total.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.processingType

enum<string>

Processing type of the order. A value outside the listed set is not rejected: it is discarded and the normal instrument-aware fallback is applied; without an enabled instrument this is Regular. Values are matched exactly, so casing must match.

Available options:

Regular,

Subscription,

CardOnFile,

UnscheduledCardOnFile,

MOTO,

InPerson

order.createdAt

string<date-time>

The order's creation date in RFC 3339 format.

order.pendingStateDuration

string

Controls how long the execution is allowed to remain in pending state. If the transaction has not reached a final state within this duration, the execution is automatically cancelled. The format should be based on the ISO 8601 standard.

Example:

"PT10M"

order.fundsTransfer

object

The order funds transfer details in case this is an AFT transaction. See FundsTransfer for every field.

Hide child attributes

order.fundsTransfer.type

string

The type of funds transfer.

order.fundsTransfer.purpose

string

A human-readable description of the purpose for the funds transfer.

order.fundsTransfer.recipient

object

Details of the individual or entity receiving the funds. See FundsTransfer.recipient for every field.

order.fundsTransfer.sender

object

Details of the individual or entity sending the funds. See FundsTransfer.sender for every field.

order.fulfillmentMethod

string

The fulfillment or shipping method used for the order (e.g. standard, express, pickup), in whatever vocabulary the merchant uses. Passed through as-is to providers that need it.

order.shipmentReference

string

The merchant's identifier for the shipment fulfilling this order.

order.accommodationData

object

Details of a lodging stay paid for by this order.

Hide child attributes

order.accommodationData.itineraryNumber

string

Your booking or itinerary reference for the stay.

Example:

"24876B62518225"

order.accommodationData.folioNumber

string

The property's folio or bill reference for the stay.

order.accommodationData.checkIn

string<date-time>

The first night of the stay, in RFC 3339 format.

order.accommodationData.checkOut

string<date-time>

The departure date, in RFC 3339 format.

order.accommodationData.propertyName

string

The name of the property hosting the stay.

Example:

"The Sea View Hotel"

order.accommodationData.propertyAddress

object

The address of the property hosting the stay.

Hide child attributes

order.accommodationData.propertyAddress.street

string

The name of the street of a postal address.

order.accommodationData.propertyAddress.doorNumber

string

The number on the door, building, or room.

order.accommodationData.propertyAddress.complement

string

Additional addressing information, 2nd line of postal address.

order.accommodationData.propertyAddress.area

string

The name of the suburb or area within a city.

order.accommodationData.propertyAddress.city

string

The name of the city of a postal address.

order.accommodationData.propertyAddress.postalCode

string

The postal code.

order.accommodationData.propertyAddress.state

string

The name of the state a postal address is in.

order.accommodationData.propertyAddress.country

object

The country where the address is in.

Hide child attributes

order.accommodationData.propertyAddress.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

order.accommodationData.propertyAddress.country.iso3

string

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

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

order.accommodationData.propertyAddress.country.name

string

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

order.accommodationData.propertyAddress.latitude

number<float>

Latitude of the address in the GPS coordinate system.

order.accommodationData.propertyAddress.longitude

number<float>

Longitude of the address in the GPS coordinate system.

order.accommodationData.propertyAddress.phone

object

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

Hide child attributes

order.accommodationData.propertyAddress.phone.number

string

required

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

Pattern: ^[0-9]+$

order.accommodationData.propertyAddress.phone.countryCode

string

International prefix of the phone, if known separately.

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

order.accommodationData.propertyAddress.alias

string

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

order.accommodationData.propertyAddress.name

string

Name of the person to whom the address belongs to.

order.accommodationData.propertyAddress.lastName

string

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

order.accommodationData.propertyAddress.email

string

Email of the person to whom the address belongs to.

order.accommodationData.guests

object[]

The guests staying at the property.

Hide child attributes

order.accommodationData.guests.name

string

The name of the passenger.

order.accommodationData.guests.lastName

string

The last name of the passenger.

order.accommodationData.guests.phone

object

The phone number of the passenger.

Hide child attributes

order.accommodationData.guests.phone.number

string

required

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

Pattern: ^[0-9]+$

order.accommodationData.guests.phone.countryCode

string

International prefix of the phone, if known separately.

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

order.accommodationData.guests.passengerType

enum<string>

The type of the passenger.

Available options:

adult,

child,

infant,

senior

order.accommodationData.guests.email

string

The email of the passenger.

order.accommodationData.propertyPhone

object

The contact number of the property hosting the stay. Required by some providers when sending lodging data to the card schemes.

Hide child attributes

order.accommodationData.propertyPhone.number

string

required

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

Pattern: ^[0-9]+$

order.accommodationData.propertyPhone.countryCode

string

International prefix of the phone, if known separately.

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

order.accommodationData.customerServicePhone

object

Your customer service contact number. Required by some providers when sending lodging data to the card schemes.

Hide child attributes

order.accommodationData.customerServicePhone.number

string

required

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

Pattern: ^[0-9]+$

order.accommodationData.customerServicePhone.countryCode

string

International prefix of the phone, if known separately.

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

order.accommodationData.rooms

object[]

Every room booked under this stay.

Hide child attributes

order.accommodationData.rooms.nights

integer

The number of nights this room is booked for.

Example:

2

order.accommodationData.rooms.dailyRate

object

The nightly rate for this room. Send the rate itself rather than a stay total: dividing a total by nights loses precision when the division is not exact, and providers expect the true nightly figure.

Hide child attributes

order.accommodationData.rooms.dailyRate.value

string

required

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

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

Example:

"12.50"

order.accommodationData.rooms.dailyRate.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.accommodationData.rooms.dailyTax

object

The nightly tax for this room, on the same basis as dailyRate.

Hide child attributes

order.accommodationData.rooms.dailyTax.value

string

required

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

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

Example:

"12.50"

order.accommodationData.rooms.dailyTax.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

order.accommodationData.charges

object[]

Charges associated with the stay beyond the room rates themselves.

Hide child attributes

order.accommodationData.charges.type

enum<string>

The kind of charge.

Available options:

lodging,

noShow,

cancellation,

restaurant,

miniBar,

telephone,

giftShop,

laundry,

other

order.accommodationData.charges.amount

object

The value of the charge.

Hide child attributes

order.accommodationData.charges.amount.value

string

required

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

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

Example:

"12.50"

order.accommodationData.charges.amount.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

customer

object

The customer placing the order.

Hide child attributes

customer.reference

string

Customer reference number specified by the merchant. Defaults to holderReference of the execution if not specified.

customer.name

string

The full name (or first name, if you can provide lastName separate) of the customer.

customer.lastName

string

Last name of the customer (if required to be separate from name).

customer.email

string

Email address of the customer.

customer.type

string

Customer type specified by the merchant.

customer.phone

object

Phone of the customer.

Hide child attributes

customer.phone.number

string

required

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

Pattern: ^[0-9]+$

customer.phone.countryCode

string

International prefix of the phone, if known separately.

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

customer.birthDate

string<date>

Date of birth of the customer.

customer.language

string

POSIX locale string identifying the language used to communicate to the customer.

Pattern: ^[a-z]{2}(_[A-Z]+)?$

customer.country

object

Country of registration the customer. Can be different than the order and delivery countries.

Hide child attributes

customer.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

customer.country.iso3

string

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

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

customer.country.name

string

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

customer.identityCardNumber

string

The customer's identity number, e.g. passport, national ID, etc.

customer.identityCardType

string

The type of the customer's identity card, e.g. passport, national ID, etc.

customer.createdAt

string<date-time>

The customer's account creation date in RFC 3339 format. Required for Tabby integrations.

customer.updatedAt

string<date-time>

The customer's account last-updated date in RFC 3339 format.

customer.passwordChangedAt

string<date-time>

The date the customer last changed their account password, in RFC 3339 format. Used as a 3-D Secure 2 risk signal: issuers treat a recent credential change as account-takeover risk.

customer.previousPurchaseCount

integer

Number of previous purchases the customer made with the merchant. Required for Tabby integrations.

customer.previousOrders

object[]

The customer's previous orders with the merchant, used for order history based pre-scoring (e.g. BNPL providers). Required for Tabby integrations.

Hide child attributes

customer.previousOrders.purchasedAt

string<date-time>

Date and time the order was purchased, in RFC 3339 format.

customer.previousOrders.amount

object

Amount of the previous order.

Hide child attributes

customer.previousOrders.amount.value

string

required

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

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

Example:

"12.50"

customer.previousOrders.amount.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

customer.previousOrders.paymentMethod

string

Payment method used for the previous order, e.g. card, cod.

customer.previousOrders.status

string

Status of the previous order, e.g. complete, refunded, canceled.

customer.previousOrders.items

object[]

List of details per item in the previous order (same shape as an order's lines).

Hide child attributes

customer.previousOrders.items.name

string

The name of the item.

customer.previousOrders.items.description

string

The description of the item.

customer.previousOrders.items.product

object

The details of the product item.

Hide child attributes

customer.previousOrders.items.product.type

enum<string>

The type of the product item.

Available options:

physical,

digital,

service

customer.previousOrders.items.categoryId

string

Category identifier of the item on the merchant's system.

customer.previousOrders.items.type

enum<string>

The type of the item. the line value will be added to the order total in case of lineItem, tax and subtracted from order total in case of discount.

Available options:

lineItem,

discount,

tax

customer.previousOrders.items.quantity

integer

How many instances of this item are part of the order.

customer.previousOrders.items.unitPrice

object

How much does a unit of the item cost.

Hide child attributes

customer.previousOrders.items.unitPrice.value

string

required

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

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

Example:

"12.50"

customer.previousOrders.items.unitPrice.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

customer.previousOrders.items.total

object

Cost of unit price multiplied by quantity with the tax and discount applied.

Hide child attributes

customer.previousOrders.items.total.value

string

required

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

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

Example:

"12.50"

customer.previousOrders.items.total.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

customer.previousOrders.items.taxPercentage

object

Tax percentage that applies to the specific item, applicable only where item.type == lineItem, will be ignored when not providing item.unitPrice.

Hide child attributes

customer.previousOrders.items.taxPercentage.value

string

required

A percentage value up to 2 decimal precision.

Pattern: ^((100)|(\d{1,2}(\.\d*)?))$

Example:

"12.50"

customer.previousOrders.items.taxCode

enum<string>

Tax code classifying the item for tax calculation.

Available options:

businessSaas,

consumerSaas,

businessSaasSecurity,

consumerSaasSecurity,

businessSaasStorage,

consumerSaasStorage,

softwareOnprem,

businessPaas,

consumerPaas,

businessIaas,

consumerIaas,

businessWebHosting,

consumerWebHosting,

businessDomainNames,

consumerDomainNames,

businessSoftwareDownload,

consumerSoftwareDownload,

businessSoftwareMaintenanceOptional,

consumerSoftwareMaintenanceOptional,

businessDigitalSubscription,

consumerDigitalSubscription,

businessGamingSubscription,

consumerGamingSubscription,

businessVideoSubscription,

consumerVideoSubscription,

businessPhotographySubscription,

consumerPhotographySubscription,

businessMusicSubscription,

consumerMusicSubscription,

businessEbookSubscription,

consumerEbookSubscription,

businessInAppSubscription,

consumerInAppSubscription,

businessDatasetSubscription,

consumerDatasetSubscription,

businessDigitalPermanent,

consumerDigitalPermanent,

businessGamingPermanent,

consumerGamingPermanent,

businessVideoPermanent,

consumerVideoPermanent,

businessPhotographyPermanent,

consumerPhotographyPermanent,

businessMusicPermanent,

consumerMusicPermanent,

businessNft,

consumerNft,

businessEbookPermanent,

consumerEbookPermanent,

businessInAppPermanent,

consumerInAppPermanent,

businessDatasetPermanent,

consumerDatasetPermanent,

businessDigitalAdvertising,

consumerDigitalAdvertising,

exempt

customer.previousOrders.items.servicePeriod

object

The billing period this line covers, for a recurring/subscription charge. Omit for one-time line items.

Hide child attributes

customer.previousOrders.items.servicePeriod.startDate

string<date-time>

required

Start of the billing period this line covers.

customer.previousOrders.items.servicePeriod.endDate

string<date-time>

required

End of the billing period this line covers.

customer.previousOrders.items.totalDiscount

object

The total discount applied on this item (quantity x discount per item), applicable only where item.type == lineItem, will be ignored when not providing item.unitPrice.

Hide child attributes

customer.previousOrders.items.totalDiscount.value

string

required

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

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

Example:

"12.50"

customer.previousOrders.items.totalDiscount.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

customer.previousOrders.items.totalTax

object

The total tax added for this item (quantity x tax per item), applicable only where items.type = lineItem, will be ignored when not providing item.unitPrice.

Hide child attributes

customer.previousOrders.items.totalTax.value

string

required

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

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

Example:

"12.50"

customer.previousOrders.items.totalTax.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

customer.previousOrders.items.id

string

Identifier of the item on the merchant's system.

customer.previousOrders.items.brand

string

The manufacturer or brand name of the item.

customer.previousOrders.items.weight

number<float>

The weight of the item, in kilograms.

customer.previousOrders.items.links

object

Relevant links about the item.

Hide child attributes

customer.previousOrders.items.links.productUrl

string

URL of the product information page.

customer.previousOrders.items.links.imageUrl

string

URL of the image of the item.

customer.previousOrders.items.travelTicket

object

Details about the travel ticket.

Hide child attributes

customer.previousOrders.items.travelTicket.ticketId

string

The ID of the travel ticket.

customer.previousOrders.items.travelTicket.type

enum<string>

The mode of transport the travel ticket is for.

Available options:

bus,

air

customer.previousOrders.items.travelTicket.passengers

object[]

The passengers on the travel ticket.

Hide child attributes

customer.previousOrders.items.travelTicket.passengers.name

string

The name of the passenger.

customer.previousOrders.items.travelTicket.passengers.lastName

string

The last name of the passenger.

customer.previousOrders.items.travelTicket.passengers.phone

object

The phone number of the passenger.

Hide child attributes

customer.previousOrders.items.travelTicket.passengers.phone.number

string

required

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

Pattern: ^[0-9]+$

customer.previousOrders.items.travelTicket.passengers.phone.countryCode

string

International prefix of the phone, if known separately.

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

customer.previousOrders.items.travelTicket.passengers.passengerType

enum<string>

The type of the passenger.

Available options:

adult,

child,

infant,

senior

customer.previousOrders.items.travelTicket.passengers.email

string

The email of the passenger.

customer.previousOrders.items.travelTicket.routes

object[]

The routes on the travel ticket.

Hide child attributes

customer.previousOrders.items.travelTicket.routes.legs

object[]

The legs on the route.

Hide child attributes

customer.previousOrders.items.travelTicket.routes.legs.legId

string

The ID of the leg.

customer.previousOrders.items.travelTicket.routes.legs.departure

object

A point on a travel ticket leg.

Hide child attributes

customer.previousOrders.items.travelTicket.routes.legs.departure.city

string

The city of the point.

customer.previousOrders.items.travelTicket.routes.legs.departure.country

object

The country of the point.

Hide child attributes

customer.previousOrders.items.travelTicket.routes.legs.departure.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

customer.previousOrders.items.travelTicket.routes.legs.departure.country.iso3

string

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

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

customer.previousOrders.items.travelTicket.routes.legs.departure.country.name

string

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

customer.previousOrders.items.travelTicket.routes.legs.departure.airportCode

string

The 3-letter IATA airport code of the point, for air legs.

Example:

"AMS"

customer.previousOrders.items.travelTicket.routes.legs.departure.time

string<date-time>

The time of the point.

customer.previousOrders.items.travelTicket.routes.legs.arrival

object

A point on a travel ticket leg.

Hide child attributes

customer.previousOrders.items.travelTicket.routes.legs.arrival.city

string

The city of the point.

customer.previousOrders.items.travelTicket.routes.legs.arrival.country

object

The country of the point.

Hide child attributes

customer.previousOrders.items.travelTicket.routes.legs.arrival.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

customer.previousOrders.items.travelTicket.routes.legs.arrival.country.iso3

string

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

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

customer.previousOrders.items.travelTicket.routes.legs.arrival.country.name

string

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

customer.previousOrders.items.travelTicket.routes.legs.arrival.airportCode

string

The 3-letter IATA airport code of the point, for air legs.

Example:

"AMS"

customer.previousOrders.items.travelTicket.routes.legs.arrival.time

string<date-time>

The time of the point.

customer.previousOrders.items.travelTicket.routes.legs.carrier

object

The company operating the leg.

Hide child attributes

customer.previousOrders.items.travelTicket.routes.legs.carrier.code

string

The 2-letter IATA airline code, for air legs.

Example:

"KL"

customer.previousOrders.items.travelTicket.routes.legs.carrier.name

string

The name of the carrier.

clientContext

object

Data describing the customer's device or browser.

Hide child attributes

clientContext.ipAddress

string

IP address of the device that customer used to place the order. Can be IPv4 or IPv6.

clientContext.userAgent

string

The user-agent header supplied by the customer's browser.

clientContext.acceptHeader

string

The accept header supplied by the customer's browser.

clientContext.clientType

Desktop computer via web browser.

Available options:

desktop

clientContext.osType

enum<string>

Type of Operating System that the customer is using.

Available options:

ios,

android

clientContext.osVersion

string

Version of Operating System that the customer is using.

clientContext.deviceFingerprint

string

Fingerprint of the device the customer is using.

clientContext.javaEnabled

boolean

Flag indicating if the customer's browser is able to execute Java.

clientContext.javaScriptEnabled

boolean

Flag indicating if the customer's browser is able to execute JavaScript.

clientContext.cookiesAccepted

boolean

Flag indicating if the customer's browser accepts cookies.

clientContext.language

string

Locale string identifying the language of the device or browser, e.g. pt, es_UY, en-US. Both - and _ are accepted.

Pattern: ^[a-z]{2}([_-][A-Z]+)?$

clientContext.colorDepth

integer

The color depth of the customer's browser in bits per pixel.

clientContext.screenHeight

integer

The pixel height of the customer's screen.

clientContext.screenWidth

integer

The pixel width of the customer's screen.

clientContext.timeZoneOffset

integer

Time difference between UTC time and the customer's browser local time, in minutes.

clientContext.origin

string

The URL from where the order is being placed, e.g. https://merchant.com/checkout.

clientContext.host

string

The domain name from which the order is being placed, e.g. merchant.com.

vendor

object

Description of a vendor that provides the order.

Hide child attributes

vendor.reference

string

Reference of the vendor in the merchant's system.

vendor.name

string

Name of the vendor.

vendor.address

object

Address of the vendor.

Hide child attributes

vendor.address.street

string

The name of the street of a postal address.

vendor.address.doorNumber

string

The number on the door, building, or room.

vendor.address.complement

string

Additional addressing information, 2nd line of postal address.

vendor.address.area

string

The name of the suburb or area within a city.

vendor.address.city

string

The name of the city of a postal address.

vendor.address.postalCode

string

The postal code.

vendor.address.state

string

The name of the state a postal address is in.

vendor.address.country

object

The country where the address is in.

Hide child attributes

vendor.address.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

vendor.address.country.iso3

string

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

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

vendor.address.country.name

string

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

vendor.address.latitude

number<float>

Latitude of the address in the GPS coordinate system.

vendor.address.longitude

number<float>

Longitude of the address in the GPS coordinate system.

vendor.address.phone

object

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

Hide child attributes

vendor.address.phone.number

string

required

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

Pattern: ^[0-9]+$

vendor.address.phone.countryCode

string

International prefix of the phone, if known separately.

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

vendor.address.alias

string

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

vendor.address.name

string

Name of the person to whom the address belongs to.

vendor.address.lastName

string

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

vendor.address.email

string

Email of the person to whom the address belongs to.

vendor.device

object

Details about the device used by the vendor that provides the order.

Hide child attributes

vendor.device.reference

string

Unique reference of the device (e.g. serial number).

vendor.subMerchants

object[]

A list of sub-sellers for Payment Facilitator transactions.

Hide child attributes

vendor.subMerchants.id

string

Unique identifier for the sub-merchant.

vendor.subMerchants.name

string

The name of the sub-merchant.

vendor.subMerchants.mcc

string

The sub-merchant's 4-digit Merchant Category Code (MCC).

vendor.subMerchants.address

object

The physical location of the sub-merchant.

Hide child attributes

vendor.subMerchants.address.street

string

The name of the street of a postal address.

vendor.subMerchants.address.doorNumber

string

The number on the door, building, or room.

vendor.subMerchants.address.complement

string

Additional addressing information, 2nd line of postal address.

vendor.subMerchants.address.area

string

The name of the suburb or area within a city.

vendor.subMerchants.address.city

string

The name of the city of a postal address.

vendor.subMerchants.address.postalCode

string

The postal code.

vendor.subMerchants.address.state

string

The name of the state a postal address is in.

vendor.subMerchants.address.country

object

The country where the address is in.

Hide child attributes

vendor.subMerchants.address.country.code

string

required

ISO 3166-1 alpha-2 country code.

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

vendor.subMerchants.address.country.iso3

string

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

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

vendor.subMerchants.address.country.name

string

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

vendor.subMerchants.address.latitude

number<float>

Latitude of the address in the GPS coordinate system.

vendor.subMerchants.address.longitude

number<float>

Longitude of the address in the GPS coordinate system.

vendor.subMerchants.address.phone

object

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

Hide child attributes

vendor.subMerchants.address.phone.number

string

required

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

Pattern: ^[0-9]+$

vendor.subMerchants.address.phone.countryCode

string

International prefix of the phone, if known separately.

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

vendor.subMerchants.address.alias

string

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

vendor.subMerchants.address.name

string

Name of the person to whom the address belongs to.

vendor.subMerchants.address.lastName

string

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

vendor.subMerchants.address.email

string

Email of the person to whom the address belongs to.

vendor.subMerchants.amount

object

The amount of the payment corresponding to the sub-merchant.

Hide child attributes

vendor.subMerchants.amount.value

string

required

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

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

Example:

"12.50"

vendor.subMerchants.amount.currency

string

required

ISO 3-letter currency code.

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

Example:

"EUR"

risk

object

Configuration values for the risk prevention check.

Hide child attributes

risk.score

string

Score provided by an external fraud prevention system.

risk.skipPaymentProviderRules

boolean

True if the provider should skip the risk rules.

risk.skipFraudDecision

boolean

True if fraud-check providers should bypass their own review/decisioning for this transaction (e.g. a trusted customer, or a payment whose liability has already shifted to the issuer via 3DS). Typically set by the merchant's workflow rather than the caller directly.

risk.force3DS

boolean

deprecated

Deprecated, use threeDSMode instead. True if we should request the provider to force a 3DS process. The actual execution of 3DS will depend on its availability and configuration on the provider and the issuer.

risk.threeDSMode

enum<string>

3DS mode to send in an authorize request to a PSP.

Available options:

Skip,

Force,

Default

risk.allowNative3DS

boolean

True if we should allow native experience in mobile devices when 3DS 2.x is triggered. If false, we will prefer redirection-based flows.

risk.sessionId

string

deprecated

Deprecated in favour of sessions. Session ID provided by an external fraud prevention system. Kept only for older web-SDK versions and direct API integrations that haven't migrated yet.

risk.sessions

object[]

Session/device IDs for one or more external fraud prevention systems. This is the standard way to provide a fraud session id, whether one provider is configured or several.

Hide child attributes

risk.sessions.provider

enum<string>

required

Identifier of the fraud prevention provider this session ID belongs to.

Available options:

riskified,

signifyd,

ravelin,

cybersource,

forter,

airwallex,

stripe,

checkout,

hyperpay

risk.sessions.sessionId

string

required

Session/device ID provided by this fraud prevention provider.

risk.sessions.providerConfigId

string<uuid>

Disambiguates multiple sessions for the same provider, when more than one configured instance of that provider is in play. Optional; omit unless more than one session for the same provider is present.

risk.exemptionIndicator

enum<string>

Indicates the exemption that you want to request in case a 3DS process is triggered.The issuer decides if the exemption is granted or not. For some types of transaction, the issuer can grant an exemption without you requesting it. Possible values are * lowValue - For payments below 30 EUR (or equivalent converted amount) are considered “low value” and might be exempt from SCA. SCA is required if the total amount is higher than 100 EUR, and every 5 transactions. * transactionRiskAnalysis - For payments through acquirers or issuers whose fraud level is below a certain threshold. * secureCorporate - For payments that use secure corporate cards, which are exempt from 3DS authentication. * trustedBeneficiary - For payments where the cardholder has already added the merchant to a trust list on their bank. * trustedBeneficiaryPrompt - For payments where the merchant would like to prompt the cardholder to add them as a trusted merchant. * dataShare - Data Sharing exemptions for transactions that are not subject to Strong Customer Authentication (SCA) compliance.

Available options:

lowValue,

transactionRiskAnalysis,

secureCorporate,

trustedBeneficiary,

trustedBeneficiaryPrompt,

dataShare

subscription

object

Configuration of a subscription process.

Option 1
Option 2
Option 3

Hide child attributes

subscription.chargeFrequency

string

Scheduled interval between subscription payments. The format should be based on the ISO 8601 standard.

subscription.expiration

string<date>

Date when recurring payments expire.

subscription.startDate

string<date>

Date when the subscription starts. Used by subscription mandates such as Pix Automático.

subscription.scheduledDate

string<date>

Date on which a recurring merchant-initiated transaction is scheduled to be processed. Submit this field for recurring MITs only when required by the selected payment method, such as certain account-to-account and direct debit payment methods.

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute