GET /options

Get APM options

get

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

amountnumber · min: 1Required

The current cart or order amount for which to retrieve available payment providers. This amount is used to filter payment methods based on their minimum and maximum amount limits. Must be a positive number greater than or equal to 1.

Example: 100

currencystringRequired

The currency for the order in ISO 4217 format (three-letter currency code, e.g., AUD, USD, GBP). This determines which payment providers are available, as providers are configured for specific currencies. The currency must match the currency you will use when creating the order.

Example: AUD

channelstringOptional

The channel alias identifier to filter payment methods by channel configuration. If provided, only payment methods enabled for this channel will be returned. If not provided, all payment methods configured without a channel (default channel) will be returned. The same channel should be passed to both the Options endpoint and the Create Order endpoint to ensure consistency. Channels allow you to configure different payment methods and credentials for different sales channels (e.g., e-commerce, mobile app, in-store).

Example: mobile-app-v2

isCapablebooleanRequired

Flag to include base64-encoded image data in the response. When set to true, the response will include the image field with base64-encoded logo data for each payment provider. When false (default), only the imageUrl field is returned. Set to true if you need to display provider logos without making additional HTTP requests.

Default: falseExample: false

Responses

200

Returns a list of APM options

application/json

termsstringRequired

A human-readable description of the payment terms for this option. Display this text to help customers understand the payment structure if the provider is a BNPL.

Example: Pay AUD 25 in 4 installments every 2 weeks with Afterpay AU.

namestring · enumRequired

The unique identifier for the APM provider. This is the provider name that should be used in the bnplProvider field when creating an order.

Example: AFTERPAY_AUPossible values:

imageUrlstringRequired

The URL of the payment provider's logo image. Use this URL to display the provider logo on your checkout page.

Example: https://widgets.qa.optty.com/images/logos/bnpl_afterpay_1.0.svg

termDurationInMonthsnumberRequired

The total duration of the payment term expressed in months. This is calculated from the installment structure and helps customers understand the repayment period.

Example: 2

termDurationInWeeksnumberRequired

The total duration of the payment term expressed in weeks. This is calculated from the installment structure and helps customers understand the repayment period.

Example: 8

recommendedbooleanRequired

Set to True for the payment method with the cheapest monthly or weekly repayment.

Example: true

maxAmountnumberRequired

The maximum cart amount the merchant has selected this provider to be enabled for.

Example: 2000

minAmountnumberRequired

The minimum cart amount the merchant has selected this provider to be enabled for.

Example: 0

prioritynumberRequired

The display priority of this payment option on the checkout page. Lower numbers indicate higher priority (priority 1 is the top of the list). Use this value to order payment methods on your checkout page, guiding customers toward preferred payment options. The priority is configured in the Universal Payment Platform (UPP).

Example: 1

lateFeesAllowedbooleanRequired

Indicates whether late fees have been configured for this payment provider. This is a configuration flag set in the UPP. It does not affect checkout functionality of the APM.

Example: false

customerFeesAllowedbooleanRequired

Indicates whether customer fees can be configured for this payment provider. This is a configuration flag set in the Universal Payment Platform (UPP).

Example: false

customerFeesstring · enumRequired

The customer fees configuration status. Indicates whether customer fees are enabled, disabled, or set to custom. Use this along with customerFeesCustomText to display fee information to customers that they must accept before continue with payment.

Example: disabledPossible values:

lateFeesstring · enumRequired

The late fees configuration status. Indicates whether late fees are enabled, disabled, or set to custom. Use this along with lateFeesCustomText to display fee information to customers. This does not affect checkout funcitonality.

Example: disabledPossible values:

lateFeesCustomTextstringRequired

Custom text configured by the merchant regarding late fees for this payment provider. Display this text to inform customers about potential late payment fees. This text is configured in the Universal Payment Platform UPP by the merchant.

customerFeesCustomTextstringRequired

Custom text configured by the merchant regarding processing fees for this payment provider. Display this text to inform customers about any processing fees incured and ensure they have accepted the fee. This text is configured in the UPP.

Example: Custom Customer fee message

customerFeesFlatnumberRequired

The flat rate customer fee amount charged to customers for using this payment method. This is a fixed fee amount regardless of order value.

Example: 0

customerFeesPercentagenumberRequired

The percentage rate for customer fees charged to customers for using this payment method. This is calculated as a percentage of the order amount.

Example: 0

surchargeCapnumberRequired

The maximum cap on the surcharge amount that can be charged to customers. If the calculated surcharge exceeds this cap, the surcharge will be limited to this amount.

Example: 0

providerFeesnumberRequired

The flat rate provider fee charged by the payment provider. This is a fixed fee amount that the merchant pays to the provider.

Example: 0

providerFeesPercentagenumberRequired

The percentage rate for provider fees charged by the payment provider. This is calculated as a percentage of the order amount that the merchant pays to the provider. This is entered on the UPP by the merchant.

Example: 0

interestRateAllowedbooleanRequired

Indicates whether interest rates can be configured for this payment provider. This is a configuration flag set in the Universal Payment Platform (UPP).

Example: false

isActivebooleanRequired

Indicates whether this payment provider is currently active and available for use. Only active providers should be displayed to customers. Inactive providers have been disabled in the Universal Payment Platform (UPP) by the merchant.

Example: true

createdAtstringRequired

The ISO 8601 timestamp (UTC) when this payment provider configuration was created in the Universal Payment Platform (UPP).

Example: 2024-01-25T23:31:20.091Z

updatedAtstringRequired

The ISO 8601 timestamp (UTC) when this payment provider configuration was last updated in the Universal Payment Platform (UPP).

Example: 2024-01-26T10:30:30.133Z

userNamestringRequired

The username of the merchant or administrator who created or last modified this payment provider configuration in the Universal Payment Platform (UPP).

Example: Merchant

providerNamestringRequired

The display name of the payment provider. This is typically the same as the name field but may include additional formatting or branding.

Example: AFTERPAY_AU

currencystring · enumRequired

The currency this payment provider is configured for. This must match the currency passed in the Get Options request.

Example: AUDPossible values:

paymentTypestringRequired

The type or category of the payment provider (e.g., "BNPL", "card", "digital wallet").

Example: BNPL

preferredDisplayModestringRequired

The preferred display mode configured by the merchant for this payment provider. Indicates how the payment interface should be displayed (e.g., "REDIRECT" for redirect-based flows, "IN_CONTEXT" for embedded flows). This will determine the payment flow type if an order is initiated with our widgets.

Example: REDIRECT

incontextDisplayModestringRequired

The in-context display mode supported by this payment provider. Indicates how the provider's payment interface will be displayed within the merchant's checkout flow when using IN_CONTEXT mode with our widgets (e.g., "IFRAME" for embedded iframe, "POPUP" for popup overlay).

Example: IFRAME

paymentStatusFetchEnabledbooleanRequired

Indicates whether payment status will be automatically fetched after processing of order using our widgets. When enabled, our widgets will poll for payment status updates after completion to return on the callback function.

Example: false

customProviderLogostringRequired

Custom Logo for Provider

get

/options

HTTPcURLJavaScriptPython

GET /options?amount=1&currency=text&isCapable=false HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Returns a list of APM options

[
  {
    "terms": "Pay AUD 25 in 4 installments every 2 weeks with Afterpay AU.",
    "name": "AFTERPAY_AU",
    "imageUrl": "https://widgets.qa.optty.com/images/logos/bnpl_afterpay_1.0.svg",
    "instalment": {
      "rate": {
        "amount": 25,
        "currency": "AUD"
      },
      "termDuration": 8,
      "termUnit": "weeks"
    },
    "monthlyCost": {
      "amount": 50,
      "currency": "AUD"
    },
    "termDurationInMonths": 2,
    "weeklyCost": {
      "amount": 12.5,
      "currency": "AUD"
    },
    "termDurationInWeeks": 8,
    "recommended": true,
    "maxAmount": 2000,
    "minAmount": 0,
    "priority": 1,
    "lateFeesAllowed": false,
    "customerFeesAllowed": false,
    "customerFees": "disabled",
    "lateFees": "disabled",
    "lateFeesCustomText": "",
    "customerFeesCustomText": "Custom Customer fee message",
    "customerFeesFlat": 0,
    "customerFeesPercentage": 0,
    "surchargeCap": 0,
    "providerFees": 0,
    "providerFeesPercentage": 0,
    "interestRateAllowed": false,
    "isActive": true,
    "createdAt": "2024-01-25T23:31:20.091Z",
    "updatedAt": "2024-01-26T10:30:30.133Z",
    "userName": "Merchant",
    "providerName": "AFTERPAY_AU",
    "currency": "AUD",
    "checkoutConfig": {
      "content": "text",
      "iframeUrl": "text",
      "button": {
        "type": "text",
        "text": "text",
        "color": "text",
        "background": "text",
        "position": "text",
        "size": "text"
      },
      "termsCondition": {
        "type": "text",
        "content": "text",
        "linkText": "text"
      }
    },
    "productDetailsConfig": {
      "content": "text"
    },
    "paymentType": "BNPL",
    "preferredDisplayMode": "REDIRECT",
    "incontextDisplayMode": "IFRAME",
    "paymentStatusFetchEnabled": false,
    "popupOverlayConfig": {
      "title": "Payment in progress",
      "message": "Click anywhere to continue payment!"
    },
    "requiredFields": {
      "billingAddress": {
        "email": true,
        "phoneNumber": true,
        "region": false,
        "state": true,
        "postalCode": true,
        "city": true,
        "country": true,
        "streetAddress": true,
        "streetAddress2": false
      }
    },
    "customProviderLogo": "text"
  }
]