Lookup payment options

Introduction

Payment Options are the payment methods and instruments available to a customer in a given context. You configure rules for their availability in the Payrails Portal and then use the lookup endpoint to synchronously determine and present the right payment options to customers on the client side.

Steps

1. Get the execution ID

For your request to the lookup endpoint, you’ll need the ID of the workflow execution. You can find the ID in the response to the creation of this workflow execution, with the key id

2. Make a POST request

Make a POST request to the Lookup payment options endpoint, where executionId is the ID from the previous step. In your request, include:

amount.value: The decimal amount of the major currency unit, in any precision
amount.currency: ISO 3-letter currency code

For example:

{
  "amount": {
    "value": "12.50",
    "currency": "EUR"
  },
  "meta": {
    "country": {
      "code": "DE"
    },
    "customer": {
      "reference": "customer123",
      "country": {
        "code": "DE"
      }
    },
    "clientContext": {
      "osType": "ios",
      "language": "de-DE"
    },
    "allowedPaymentMethods": ["card", "klarna"]
  }
}

For the complete request schema, refer to the Lookup payment options API reference.

The payment options available to a customer vary according to context. If the context changes during checkout (for example, the total amount changes), look up the payment options again and refresh the results to ensure the payment methods and instruments displayed to your consumer remain accurate.

3. Receive the lookup response

If the lookup was successfully executed, you’ll find the following in the response:

actionId: The unique identifier for this capture execution
data.paymentCompositionOptions: This is the list of payment methods and payment instruments that can be used to complete the execution.
links: Links to the next possible actions that can be taken

For example:

{
  "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",
            "paymentMethod": "card",
            "description": "Personal card.",
            "fingerprint": "739abff0-406a-4d32-8cfb-701e12be5848",
            "status": "created",
            "data": {
              "network": "visa",
              "bin": "411111",
              "suffix": "1111",
              "expiryMonth": "10",
              "expiryYear": "2026",
              "holderName": "John Doe"
            },
            "meta": {
              "communityCode": "GAP",
              "userKey": "9890124569"
            }
          }
        ]
      }
    ]
  },
  "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"
    }
  }
}

By default, the paymentInstruments list inside each of the payment methods returned includes only the ones with status Created or Enabled for the Holder that created the execution. This means that any inactive, expired, or blocked instrument will be excluded to avoid payment rejections.To query all the instruments for that holder regardless of their current state, use the List Instruments API.

For the complete response schema, refer to the Lookup payment options API reference.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Introduction

Steps

1. Get the execution ID

2. Make a POST request

3. Receive the lookup response

​Introduction

​Steps

​1. Get the execution ID

​2. Make a POST request

​3. Receive the lookup response

Introduction

Steps

1. Get the execution ID

2. Make a POST request

3. Receive the lookup response