Primer · Schema
PaymentCreationAPIRequest
paymentspayment orchestrationpayment processingfintechfraud detectionsmart routingcheckoutpayment methodsreconciliationwebhooks
Properties
| Name | Type | Description |
|---|---|---|
| orderId | string | Your reference for the payment. |
| currencyCode | object | The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g. use `USD` for US dollars. |
| amount | integer | The amount you would like to charge the customer, in minor units. e.g. for $7, use `700`. Some currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is |
| order | object | More information associated with the order. |
| paymentMethodToken | string | The payment method token used to authorize the payment. |
| customerId | string | A unique identifier for your customer. This attribute is required if `paymentMethod.vaultOnSuccess` is set to `True`. |
| customer | object | More information associated with the customer. |
| metadata | object | Additional data to be used throughout the payment lifecycle. A dictionary of key-value pairs where the values can only be strings or integers. e.g. `{"productId": 1001, "merchantId": "a13bsd62s"}` |
| paymentMethod | object | Enable certain options associated with the payment method. |
| expand | object |
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "PaymentCreationAPIRequest",
"$defs": {
"AccountFundingTypeEnum": {
"title": "AccountFundingTypeEnum",
"enum": [
"CREDIT",
"DEBIT",
"PREPAID",
"CHARGE",
"DEFERRED_DEBIT",
"UNKNOWN"
],
"type": "string",
"description": "An enumeration."
},
"ApayaCustomerTokenAPISchema": {
"title": "ApayaCustomerTokenAPISchema",
"required": [
"mx"
],
"type": "object",
"properties": {
"mx": {
"title": "Mx",
"type": "string"
},
"mnc": {
"title": "Mnc",
"type": "integer",
"format": "int64"
},
"mcc": {
"title": "Mcc",
"type": "integer",
"format": "int64"
}
}
},
"BinDataAPISchema": {
"title": "BinDataAPISchema",
"required": [
"network",
"regionalRestriction",
"accountNumberType",
"accountFundingType",
"prepaidReloadableIndicator",
"productUsageType",
"productCode",
"productName"
],
"type": "object",
"properties": {
"network": {
"$ref": "#/components/schemas/CardNetworkEnum"
},
"issuerCountryCode": {
"$ref": "#/components/schemas/CountryCodeEnum"
},
"issuerName": {
"title": "Issuername",
"type": "string"
},
"issuerCurrencyCode": {
"$ref": "#/components/schemas/Currency"
},
"regionalRestriction": {
"$ref": "#/components/schemas/CardRegionRestrictionEnum"
},
"accountNumberType": {
"$ref": "#/components/schemas/CardAccountNumberTypeEnum"
},
"accountFundingType": {
"$ref": "#/components/schemas/AccountFundingTypeEnum"
},
"prepaidReloadableIndicator": {
"$ref": "#/components/schemas/PrepaidReloadableEnum"
},
"productUsageType": {
"$ref": "#/components/schemas/CardProductTypeEnum"
},
"productCode": {
"title": "Productcode",
"type": "string"
},
"productName": {
"title": "Productname",
"type": "string"
}
}
},
"BlockingPaymentActionTypeEnum": {
"title": "BlockingPaymentActionTypeEnum",
"enum": [
"3DS_AUTHENTICATION",
"USE_PRIMER_SDK",
"PAYMENT_METHOD_VOUCHER",
"PROCESSOR_3DS"
],
"type": "string",
"description": "An enumeration."
},
"CardAccountNumberTypeEnum": {
"title": "CardAccountNumberTypeEnum",
"enum": [
"PRIMARY_ACCOUNT_NUMBER",
"NETWORK_TOKEN",
"DIGITAL_PAN",
"UNKNOWN"
],
"type": "string",
"description": "An enumeration."
},
"CardNetworkEnum": {
"title": "CardNetworkEnum",
"enum": [
"AMEX",
"DANKORT",
"DINERS_CLUB",
"DISCOVER",
"EFTPOS",
"ENROUTE",
"ELO",
"HIPER",
"INTERAC",
"JCB",
"MAESTRO",
"MASTERCARD",
"MIR",
"PRIVATE_LABEL",
"UNIONPAY",
"VISA",
"CARTES_BANCAIRES",
"OTHER"
],
"type": "string",
"description": "The list of available card networks.\n"
},
"CardProductTypeEnum": {
"title": "CardProductTypeEnum",
"enum": [
"CONSUMER",
"BUSINESS",
"GOVERNMENT",
"UNKNOWN"
],
"type": "string",
"description": "An enumeration."
},
"CardRegionRestrictionEnum": {
"title": "CardRegionRestrictionEnum",
"enum": [
"DOMESTIC_USE_ONLY",
"NONE",
"UNKNOWN"
],
"type": "string",
"description": "An enumeration."
},
"ClientSessionUpdateAPIRequest": {
"title": "ClientSessionUpdateAPIRequest",
"type": "object",
"properties": {
"clientToken": {
"title": "Client token",
"type": "string",
"description": "Client token for use in the Primer-JS SDK obtained via `POST` /client-session API call."
},
"customerId": {
"title": "The ID of the customer using the checkout.",
"type": "string",
"description": "A unique identifier for your customer."
},
"orderId": {
"title": "Order ID",
"type": "string",
"description": "Your reference for the order."
},
"currencyCode": {
"title": "Currency",
"type": "string",
"description": "The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g. use `USD` for US dollars.\n"
},
"amount": {
"title": "Payment amount",
"minimum": 0.0,
"type": "integer",
"format": "int64",
"description": "The amount you would like to charge the customer, in minor units. e.g. for $7, use `700`.\n\nSome currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for \u00a5100, use `100`.\n\nIf the amount is provided on this level, it would override any amount calculated from the provided line items, shipping and other amounts."
},
"metadata": {
"title": "Payment Metadata",
"type": "object",
"description": "Additional data to be used throughout the payment lifecycle.\n\nProvide the entire object to update it. Anything provided previously will be overwritten.\n"
},
"customer": {
"$ref": "#/components/schemas/CheckoutCustomerDetailsAPISchema",
"title": "Customer Details",
"description": "More information associated with the customer.\n\nEach of the fields in this object must be updated in its entirety, i.e. provide the entire object to update it. Anything provided previously will be overwritten.\n"
},
"order": {
"$ref": "#/components/schemas/OrderDetailsAPISchema",
"title": "Order Details",
"description": "More information associated with the order.\n\nEach of the fields in this object must be updated in its entirety, i.e. provide the entire object to update it. Anything provided previously will be overwritten.\n"
},
"paymentMethod": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionsAPISchema",
"title": "Payment Method Options",
"description": "Enable certain options associated with the payment method. Provide the entire object to update it. Anything provided previously will be overwritten."
}
},
"additionalProperties": false,
"example": {
"clientToken": "client-session-token",
"customerId": "customer-123",
"orderId": "order-abc",
"customer": {
"emailAddress": "[email protected]"
},
"amount": 500,
"paymentMethod": {
"authorizationType": "FINAL"
},
"order": {
"lineItems": [
{
"itemId": "shoe-123",
"description": "Blue Shoe",
"amount": 100,
"quantity": 10
}
],
"countryCode": "FR"
}
}
},
"ClientSessionAPIRequest": {
"title": "ClientSessionAPIRequest",
"type": "object",
"properties": {
"orderId": {
"title": "Order identifier",
"type": "string",
"description": "Your reference for the payment.",
"minLength": 1,
"maxLength": 255
},
"currencyCode": {
"$ref": "#/components/schemas/Currency",
"title": "Currency",
"description": "The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g. use `USD` for US dollars.\n"
},
"amount": {
"title": "Payment amount",
"minimum": 0.0,
"type": "integer",
"format": "int64",
"description": "The amount you would like to charge the customer, in minor units. e.g. for $7, use `700`.\n\nSome currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for \u00a5100, use `100`.\n\nIf the amount is provided on this level, it would override any amount calculated from the provided line items, shipping and other amounts."
},
"order": {
"$ref": "#/components/schemas/OrderDetailsAPISchema",
"title": "Order Details",
"description": "More information associated with the order."
},
"customerId": {
"title": "The ID of the customer using the checkout",
"type": "string",
"description": "A unique identifier for your customer.\nCreate a client session token with a `customerId` to enable the client-side SDK to retrieve and manage your customer's saved payment methods. A client session token also enables saving payment methods against this customer id.",
"minLength": 1,
"maxLength": 255
},
"customer": {
"$ref": "#/components/schemas/CheckoutCustomerDetailsAPISchema",
"title": "Customer Details",
"description": "More information associated with the customer."
},
"metadata": {
"title": "Payment Metadata",
"type": "object",
"description": "Additional data to be used throughout the payment lifecycle.\n\nA dictionary of key-value pairs where the values can only be strings or\nintegers.\n\ne.g. `{\"productId\": 1001, \"merchantId\": \"a13bsd62s\"}`\n"
},
"paymentMethod": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionsAPISchema",
"title": "Payment Method Options",
"description": "Enable certain options associated with the payment method."
}
},
"additionalProperties": false,
"example": {
"orderId": "order-abc",
"currencyCode": "GBP",
"amount": 1000,
"order": {
"countryCode": "FR,",
"lineItems": [
{
"itemId": "shoe-123",
"description": "Blue Shoe",
"amount": 100,
"quantity": 10
}
]
},
"customerId": "customer-123",
"customer": {
"emailAddress": "[email protected]"
},
"metadata": {
"productType": "Shoes"
},
"paymentMethod": {
"descriptor": "Purchase: Shoes",
"paymentMethodType": "PAYMENT_CARD",
"vaultOnSuccess": true,
"vaultOn3DS": false,
"options": {
"PAYMENT_CARD": {
"networks": {
"VISA": {
"surcharge": {
"amount": 10
}
}
}
},
"GOOGLE_PAY": {
"surcharge": {
"amount": 20
}
}
},
"authorizationType": "ESTIMATED"
}
}
},
"OrderDetailsAPISchema": {
"title": "OrderDetailsAPISchema",
"type": "object",
"properties": {
"lineItems": {
"title": "Line Items",
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderLineItemsAPISchema"
},
"description": "The details of the line items of the order."
},
"countryCode": {
"$ref": "#/components/schemas/CountryCodeEnum",
"title": "Country Code",
"description": "The country in which the order is created"
},
"retailerCountryCode": {
"$ref": "#/components/schemas/CountryCodeEnum",
"title": "Retailer Country Code",
"description": "The country code of the retailer"
},
"fees": {
"title": "Fee Details",
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderFeesAPISchema"
},
"description": "The details of fees charged."
},
"shipping": {
"$ref": "#/components/schemas/OrderShippingAPISchema",
"title": "Shipping Details",
"description": "The details of shipping charged."
}
}
},
"OrderFeesAPISchema": {
"title": "OrderFeesAPISchema",
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"minimum": 0.0,
"type": "integer",
"format": "int64",
"description": "The fee amount charged to the customer, in minor units. e.g. for $7, use `700`."
},
"type": {
"type": "string",
"description": "The type of fee.",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"description": "A description of the fee, e.g. \"Currency Conversion Fee\".",
"minLength": 1,
"maxLength": 255
}
}
},
"OrderLineItemsAPISchema": {
"title": "OrderLineItemsAPISchema",
"description": "The details of the line items of the order.\n\nThe total amount of a line item is calculated like so: \n````\n totalAmount = (amount * quantity) - discountAmount + taxAmount\n```\n",
"type": "object",
"required": [
"amount"
],
"properties": {
"itemId": {
"title": "Item ID",
"type": "string",
"description": "A unique identifier for the line item.",
"minLength": 1,
"maxLength": 255
},
"name": {
"title": "Name",
"type": "string",
"description": "A name of the item.",
"maxLength": 255
},
"description": {
"title": "Item ID",
"type": "string",
"description": "A description of the item.",
"maxLength": 255
},
"amount": {
"minimum": 0.0,
"type": "integer",
"format": "int64",
"description": "The amount charged to the customer, in minor units. The minimum amount is 0. The maximum amount is the limit of `int64`."
},
"quantity": {
"type": "integer",
"description": "The number of the particular line item that is being ordered.",
"default": 1,
"format": "int64"
},
"discountAmount": {
"title": "Discount Amount",
"minimum": 0.0,
"type": "integer",
"format": "int64",
"description": "Any discount applicable to this item, in minor units. This discount is applied for the entire line item, and not per `quantity`."
},
"taxAmount": {
"title": "Tax Amount",
"minimum": 0.0,
"type": "integer",
"format": "int64",
"description": "The tax charged on this item, in minor units. This tax amount is applied for the entire line item, and not per `quantity`."
},
"taxCode": {
"title": "Tax Code",
"type": "string",
"description": "The tax code associated with this item, in minor units. This is required for Primer-initiated tax calculations.",
"minLength": 1,
"maxLength": 255
},
"productType": {
"$ref": "#/components/schemas/ProductTypeEnum",
"title": "Product Type",
"description": "An identifier for the product type."
},
"productData": {
"$ref": "#/components/schemas/OrderLineItemsProductDataAPISchema",
"title": "Product Data",
"description": "Details related to the product"
}
}
},
"OrderLineItemsProductDataAPISchema": {
"title": "OrderLineItemsProductDataAPISchema",
"description": "Details related to the product",
"type": "object",
"properties": {
"sku": {
"title": "SKU",
"type": "string",
"description": "The product SKU",
"minLength": 1,
"maxLength": 255
},
"brand": {
"title": "Brand",
"type": "string",
"description": "The product brand",
"minLength": 1,
"maxLength": 255
},
"color": {
"title": "Color",
"type": "string",
"description": "The product color",
"minLength": 1,
"maxLength": 255
},
"globalTradeItemNumber": {
"title": "Global Trade Item Number",
"type": "string",
"description": "The product Global Trade Item Number (e.g. ISBN)",
"minLength": 1,
"maxLength": 255
},
"manufacturerPartNumber": {
"title": "Manufacturer Part Number",
"type": "string",
"description": "The product Manufacturer Part Number",
"minLength": 1,
"maxLength": 255
},
"weight": {
"title": "Weight",
"type": "number",
"description": "The product weight",
"minimum": 0.0
},
"weightUnit": {
"title": "Weight Unit",
"type": "string",
"description": "The product weight unit (e.g. kg, g)",
"minLength": 1,
"maxLength": 255
},
"pageUrl": {
"title": "Page URL",
"type": "string",
"description": "The product page URL",
"minLength": 1,
"maxLength": 1024
}
}
},
"OrderShippingAPISchema": {
"title": "OrderShippingAPISchema",
"type": "object",
"properties": {
"amount": {
"minimum": 0.0,
"type": "integer",
"format": "int64",
"description": "The shipping amount charged to the customer, in minor units. e.g. for $7, use `700`."
},
"methodId": {
"type": "string",
"description": "Your unique identifier of the shipping method selected by the customer."
},
"methodName": {
"type": "string",
"description": "The display label for the selected shipping method (e.g. \"Standard Shipping\")."
},
"methodDescription": {
"type": "string",
"description": "The descriptive text that is displayed alongside the shipping method name."
}
}
},
"CheckoutPaymentMethodOptionsAPISchema": {
"title": "PaymentMethodOptionsAPISchema",
"type": "object",
"properties": {
"vaultOnSuccess": {
"type": "boolean",
"description": "Whether the payment method should be vaulted on a successful payment or not.",
"default": false
},
"vaultOn3DS": {
"type": "boolean",
"description": "Whether the payment method should be vaulted after a successful 3DS authentication or not.",
"default": false
},
"vaultOnAgreement": {
"type": "boolean",
"description": "Whether the payment method should be vaulted right when payment is created or not.",
"default": false
},
"descriptor": {
"title": "Payment descriptor",
"type": "string",
"description": "A description of the payment, as it would typically appear on a bank statement.",
"maxLength": 255
},
"paymentType": {
"$ref": "#/components/schemas/RecurringPaymentTypeSchema"
},
"orderedAllowedCardNetworks": {
"title": "Allowed card networks",
"type": "array",
"items": {
"$ref": "#/components/schemas/CardNetworkEnum"
},
"description": "If provided, the checkout will run the validation on the entered card number and raise an error in case the card network is not supported.\n\nThe order sets the default card network that should be used in the case of co-badged cards. \ne.g. in the case of `[\"VISA\", \"CARTES_BANCAIRES\", \"MASTERCARD\"]` - if the user enters a \"Visa\" / \"Cartes Bancaires\" card: the default is Visa.\n\nValues should be unique. \n\nIf `null` or nothing passed in the request, the following list with all card networks will be returned in the response:\n\n`[\"VISA\", \"MASTERCARD\", \"AMEX\", \"MAESTRO\", \"UNIONPAY\", \"CARTES_BANCAIRES\", \"DANKORT\", \"DINERS_CLUB\", \"DISCOVER\", \"EFTPOS\", \"ENROUTE\", \"ELO\", \"HIPER\", \"INTERAC\", \"JCB\", \"MIR\", \"OTHER\"]`\n"
},
"options": {
"title": "Payment Method Options",
"type": "object",
"description": "Additional options for the payment methods represented as dictionary \nwith key of [available payment methods](/docs/connections/payment-methods/available-payment-methods) and value of corresponding options.\n",
"properties": {
"<PAYMENT_METHOD_TYPE>": {
"type": "object",
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionAPISchema"
},
"APPLE_PAY": {
"type": "object",
"$ref": "#/components/schemas/CheckoutPaymentMethodApplePayOptionAPISchema"
},
"PAYMENT_CARD": {
"type": "object",
"$ref": "#/components/schemas/CheckoutPaymentMethodCardOptionAPISchema"
}
}
},
"authorizationType": {
"title": "Authorization Type",
"$ref": "#/components/schemas/AuthorizationTypeEnum",
"description": "Allows to adjust the authorized amount after the authorization, if supported by payment method.\n`FINAL` - the authorized amount is final and can not be adjusted. Adjusting the amount can be only done via canceling the payment and re-authorization with new amount.\n`ESTIMATED` - the amount can be adjusted after the authorization, if supported by payment method.\n"
},
"firstPaymentReason": {
"title": "First Payment Reason",
"$ref": "#/components/schemas/FirstPaymentReasonEnum",
"description": "The reason for the first payment. This is used for informing payment processors about the specific reason a payment method is being stored.\nDefaults to None if not provided.\n"
}
}
},
"CheckoutPaymentMethodOptionAPISchema": {
"title": "PaymentMethodOptionAPISchema",
"type": "object",
"description": "Options for the payment method of type `PAYMENT_METHOD_TYPE`.\n",
"required": [
"surcharge"
],
"properties": {
"surcharge": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionSurchargeAPISchema",
"title": "Surcharge",
"description": "Surcharge information"
},
"extraMerchantData": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionExtraMerchantDataAPISchema",
"title": "Extra Merchant Data",
"description": "For payments using the Klarna payment method, depending on the merchant segment and/or \nthe services available to consumers, Klarna may require additional information regarding \nthe customer, the merchant and/or the purchase. This information, referred to as extra merchant \ndata (EMD), consist of data that is typically not available at the checkout, but which enables \nKlarna to complete an assertive risk assessment, enable new promotional products and improve \nconversion rates for a boost in performance.\n"
},
"merchantName": {
"title": "Merchant name",
"type": "string",
"description": "For payments using the Apple Pay payment method, use this field to override the default merchant \nname for the Primer account from showing on the Apple Pay flow. For example, if your merchant \nname on your account is \"Company X\" but you want to display a specific store name on the Apple Pay \nflow, you can set the `merchantName` to \"Store name A\".\n"
}
}
},
"CheckoutPaymentMethodCardOptionAPISchema": {
"title": "Payment Method Card Option",
"type": "object",
"properties": {
"networks": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkAPISchema",
"title": "Card networks",
"description": "Dictionary of available card networks as a key with value of Payment Method Card Network Option."
},
"captureVaultedCardCvv": {
"type": "boolean",
"description": "Whether to capture CVV for vaulted card."
}
}
},
"CheckoutPaymentMethodOptionCardNetworkAPISchema": {
"title": "Payment Method Card Network Option",
"type": "object",
"properties": {
"AMEX": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"CARTES_BANCAIRES": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"DANKORT": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"DINERS_CLUB": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"DISCOVER": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"ENROUTE": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"ELO": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"HIPER": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"INTERAC": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"JCB": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"MAESTRO": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"MASTERCARD": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"MIR": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"PRIVATE_LABEL": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"UNIONPAY": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"VISA": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
},
"OTHER": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema"
}
},
"additionalProperties": false
},
"CheckoutPaymentMethodOptionCardNetworkSurchargeAPISchema": {
"type": "object",
"properties": {
"surcharge": {
"$ref": "#/components/schemas/CheckoutPaymentMethodOptionSurchargeAPISchema",
"title": "Surcharge",
"description": "Surcharge information"
}
}
},
"CheckoutPaymentMethodOptionSurchargeAPISchema": {
"title": "CheckoutPaymentMethodOptionSurchargeAPISchema",
"type": "object",
"properties": {
"amount": {
"type": "integer",
"minimum": 0.0,
"format": "int64",
"description": "The surcharge amount, in minor units. Surcharge amount must be used in conjunction with line item amounts, if a top level amount is passed then surcharge will not be calculated."
}
}
},
"CheckoutPaymentMethodOptionExtraMerchantDataAPISchema": {
"title": "CheckoutPaymentMethodOptionExtraMerchantDataAPISchema",
"type": "object",
"additionalProperties": true
},
"PaymentRequestPaymentMethodOptionsAPISchema": {
"title": "PaymentRequestPaymentMethodOptionsAPISchema",
"type": "object",
"properties": {
"vaultOnSuccess": {
"type": "boolean",
"description": "Whether the payment method should be vaulted on a successful payment or not.",
"default": false
},
"vaultOn3DS": {
"type": "boolean",
"description": "Whether the payment method should be vaulted after a successful 3DS authentication or not.",
"default": false
},
"vaultOnAgreement": {
"type": "boolean",
"description": "Whether the payment method should be vaulted right when payment is created or not.",
"default": false
},
"descriptor": {
"title": "Payment descriptor",
"type": "string",
"description": "A description of the payment, as it would typically appear on a bank statement.",
"maxLength": 255
},
"paymentType": {
"$ref": "#/components/schemas/RecurringPaymentTypeSchema"
},
"authorizationType": {
"$ref": "#/components/schemas/AuthorizationTypeEnum",
"title": "Authorization Type",
"description": "Allows to adjust the authorized amount after the authorization, if supported by payment method.\n`FINAL` - the authorized amount is final and can not be adjusted. Adjusting the amount can be only done via canceling the payment and re-authorization with new amount.\n`ESTIMATED` - the amount can be adjusted after the authorization, if supported by payment method.\nDefaults to `FINAL`.\n",
"default": "FINAL"
},
"firstPaymentReason": {
"title": "First Payment Reason",
"$ref": "#/components/schemas/FirstPaymentReasonEnum",
"description": "The reason for the first payment. This is used to be passed to the payment processor when creating a first payment.\nNot all payment processors support this field so ignore it if you are not requested to provide it. If not provided defaults to null.\n"
}
}
},
"Amount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Charge amount in minor units (e.g., 500 = $5.00). Some currencies, such as Japanese Yen, do not have minor units. In this case, use the value as-is (e.g., \u00a5100 = 100).\n"
},
"ApplePayLabel": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "Display label shown in the Apple Pay sheet to describe this billing option.\n"
},
"ApplePayManagementUrl": {
"type": "string",
"format": "uri",
"minLength": 1,
"maxLength": 1024,
"description": "URL where users can manage or cancel their Apple Pay billing agreements or subscriptions.\n"
},
"ApplePayPaymentDescription": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "Text shown to the user during Apple Pay authorization.\n"
},
"ApplePayBillingAgreement": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "Terms and conditions the user agrees to when authorizing Apple Pay billing.\n"
},
"ApplePayIntervalUnit": {
"type": "string",
"enum": [
"minute",
"hour",
"day",
"month",
"year"
],
"description": "Calendar unit representing part of a recurring billing interval.\n"
},
"ApplePayIntervalCount": {
"type": "integer",
"format": "int64",
"minimum": 1,
"description": "Number of calendar units that make up the full recurring interval (e.g., 1 = monthly).\n"
},
"CheckoutPaymentMethodApplePayOptionAPISchema": {
"title": "ApplePayOptions",
"type": "object",
"description": "Apple Pay configuration used in a client session's payment method options.",
"properties": {
"merchantName": {
"type": "string",
"description": "Display name for the merchant shown in the Apple Pay sheet.",
"minLength": 1,
"maxLength": 1024
},
"recurringPaymentRequest": {
"$ref": "#/components/schemas/ApplePayRecurringRequest"
},
"deferredPaymentRequest": {
"$ref
# --- truncated at 32 KB (160 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/primer/refs/heads/main/json-schema/primer-paymentcreation.json