# Initialize a Bolt payment for logged in shoppers

> Initialize a Bolt logged-in shopper's intent to pay for a cart, using the specified payment method. Payments must be finalized before indicating the payment result to the shopper. Some payment methods will finalize automatically after initialization. For these payments, they will transition directly to "finalized" and the response from Initialize Payment will contain a finalized payment.

Source: https://help.boltapp.com/api-reference/embeddable-checkout-v3/payments/paymentsinitialize

`POST /payments`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "version": "3.3.22",
    "title": "Bolt API Reference",
    "description": "A comprehensive Bolt API reference for interacting with Accounts, Payments, Orders and more.",
    "termsOfService": "https://www.boltapp.com/end-user-terms",
    "contact": {
      "name": "Bolt",
      "email": "merchantsupport@boltapp.com",
      "url": "https://help.boltapp.com/api-bolt/"
    }
  },
  "servers": [
    {
      "url": "https://{environment}.boltapp.com/v3",
      "variables": {
        "environment": {
          "enum": [
            "api",
            "api-sandbox"
          ],
          "default": "api-sandbox"
        }
      }
    }
  ],
  "paths": {
    "/payments": {
      "post": {
        "summary": "Initialize a Bolt payment for logged in shoppers",
        "operationId": "paymentsInitialize",
        "x-speakeasy-group": "Payments.LoggedIn",
        "x-speakeasy-name-override": "Initialize",
        "description": "Initialize a Bolt logged-in shopper's intent to pay for a cart, using the specified payment method. Payments must be finalized before indicating the payment result to the shopper. Some payment methods will finalize automatically after initialization. For these payments, they will transition directly to \"finalized\" and the response from Initialize Payment will contain a finalized payment.\n",
        "tags": [
          "Payments"
        ],
        "security": [
          {
            "oauth": [
              "bolt.account.manage"
            ],
            "api-key": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/x-publishable-key"
          },
          {
            "$ref": "#/components/parameters/x-merchant-client-id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/payment-initialize-request"
              },
              "examples": {
                "reference": {
                  "$ref": "#/components/examples/payment-initialize-payment-method-reference"
                },
                "credit_card": {
                  "$ref": "#/components/examples/payment-initialize-payment-method-credit-card"
                },
                "paypal": {
                  "$ref": "#/components/examples/payment-initialize-payment-method-paypal"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The payment was successfully initialized, and was either immediately finalized or is pending",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/payment-response"
                },
                "examples": {
                  "finalized": {
                    "$ref": "#/components/examples/payment-response-finalized"
                  },
                  "pending": {
                    "$ref": "#/components/examples/payment-response-pending"
                  }
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/response-payment-error"
          },
          "default": {
            "$ref": "#/components/responses/response-default"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "x-publishable-key": {
        "description": "The publicly shareable identifier used to identify your Bolt merchant division.",
        "in": "header",
        "name": "X-Publishable-Key",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "x-merchant-client-id": {
        "description": "A unique identifier for a shopper's device, generated by Bolt. The value is retrieved with `Bolt.state.merchantClientId` in your frontend context, per-shopper. This header is required for proper attribution of this operation to your analytics reports. Omitting this header may result in incorrect statistics.",
        "in": "header",
        "name": "X-Merchant-Client-Id",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "payment-initialize-request": {
        "type": "object",
        "required": [
          "cart",
          "payment_method"
        ],
        "properties": {
          "cart": {
            "$ref": "#/components/schemas/cart"
          },
          "payment_method": {
            "$ref": "#/components/schemas/payment-method-extended"
          },
          "seller_splits": {
            "items": {
              "$ref": "#/components/schemas/seller-split"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "authorization_type": {
            "type": "string",
            "description": "The type of authorization to perform. 'estimated' for pre-authorization, 'final' for final authorization.",
            "examples": [
              "final"
            ]
          },
          "auto_capture": {
            "type": "boolean",
            "description": "Whether to automatically capture the payment after authorization. If true, the payment will be captured immediately. If false, the payment will only be authorized and require a separate capture call.\n",
            "examples": [
              true
            ]
          },
          "three_ds_reference": {
            "type": "string",
            "description": "Reference value from cardinal.",
            "examples": [
              "b0f0d4d0-4630-4ec8-8f5e-a19234567890"
            ]
          },
          "co_funding": {
            "description": "Optional co-funding contribution from another merchant. Exactly one of funder_public_id or receiver_public_id must be present.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/co-funding"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "cart": {
        "required": [
          "total",
          "tax",
          "order_reference"
        ],
        "type": "object",
        "properties": {
          "order_reference": {
            "type": "string",
            "description": "This value is used by Bolt as an external reference to a given order. This reference must be unique per successful transaction.",
            "examples": [
              "order_100"
            ]
          },
          "order_description": {
            "type": "string",
            "description": "Used optionally to pass additional information like order numbers or other IDs as needed.",
            "maxLength": 1024,
            "examples": [
              "Order #1234567890"
            ]
          },
          "display_id": {
            "type": "string",
            "description": "A shopper-facing identifier corresponding to the order reference associated with this transaction.",
            "maxLength": 128,
            "examples": [
              "215614191"
            ]
          },
          "shipments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/cart-shipment"
            }
          },
          "discounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/cart-discount"
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/cart-item"
            }
          },
          "total": {
            "description": "The total amount of the cart including its items and taxes (if applicable).",
            "$ref": "#/components/schemas/amount"
          },
          "tax": {
            "$ref": "#/components/schemas/amount"
          }
        }
      },
      "cart-shipment": {
        "type": "object",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/address-reference"
          },
          "cost": {
            "$ref": "#/components/schemas/amount"
          },
          "carrier": {
            "type": "string",
            "description": "The name of the carrier selected.",
            "examples": [
              "FedEx"
            ]
          }
        }
      },
      "address-reference": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/address-reference-id"
          },
          {
            "$ref": "#/components/schemas/address-reference-explicit"
          },
          {
            "$ref": "#/components/schemas/address-reference-partial"
          }
        ],
        "discriminator": {
          "propertyName": ".tag",
          "mapping": {
            "id": "#/components/schemas/address-reference-id",
            "explicit": "#/components/schemas/address-reference-explicit",
            "partial": "#/components/schemas/address-reference-partial"
          }
        }
      },
      "address-reference-id": {
        "type": "object",
        "title": "Address ID Reference",
        "required": [
          ".tag",
          "id"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "id"
            ],
            "description": "The type of address reference",
            "examples": [
              "id"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "description": "The address's ID",
            "examples": [
              "D4g3h5tBuVYK9"
            ]
          }
        }
      },
      "address-reference-explicit": {
        "type": "object",
        "title": "Explicit Address Reference",
        "required": [
          ".tag",
          "first_name",
          "last_name",
          "street_address1",
          "locality",
          "postal_code",
          "country_code"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "explicit"
            ],
            "description": "The type of address reference",
            "x-order": 0,
            "examples": [
              "explicit"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "description": "The address's unique identifier.",
            "readOnly": true,
            "x-order": 1,
            "examples": [
              "D4g3h5tBuVYK9"
            ]
          },
          "first_name": {
            "type": "string",
            "description": "The first name of the person associated with this address.",
            "x-order": 2,
            "examples": [
              "Alice"
            ]
          },
          "last_name": {
            "type": "string",
            "description": "The last name of the person associated with this address.",
            "x-order": 3,
            "examples": [
              "Baker"
            ]
          },
          "company": {
            "type": "string",
            "description": "The company associated with this address.",
            "x-order": 4,
            "examples": [
              "ACME Corporation"
            ]
          },
          "street_address1": {
            "type": "string",
            "description": "The street address associated with this address.",
            "x-order": 5,
            "examples": [
              "535 Mission St, Ste 1401"
            ]
          },
          "street_address2": {
            "type": "string",
            "description": "Any additional, optional, street address information associated with this address.",
            "x-order": 6,
            "examples": [
              "c/o Shipping Department"
            ]
          },
          "locality": {
            "type": "string",
            "description": "The locality (e.g. city, town, etc...) associated with this address.",
            "x-order": 7,
            "examples": [
              "San Francisco"
            ]
          },
          "postal_code": {
            "type": "string",
            "description": "The postal code associated with this address.",
            "x-order": 8,
            "examples": [
              "94105"
            ]
          },
          "region": {
            "type": "string",
            "description": "The region or administrative area (e.g. state, province, county, etc...) associated with this address.",
            "x-order": 9,
            "examples": [
              "CA"
            ]
          },
          "country_code": {
            "$ref": "#/components/schemas/country-code"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The email address associated with this address.",
            "x-order": 11,
            "examples": [
              "alice@example.com"
            ]
          },
          "phone": {
            "type": "string",
            "format": "phone",
            "description": "The phone number associated with this address.",
            "x-order": 12,
            "examples": [
              "+14155550199"
            ]
          }
        }
      },
      "country-code": {
        "type": "string",
        "description": "The country (in its ISO 3166 alpha-2 format) associated with this address.",
        "enum": [
          "AF",
          "AX",
          "AL",
          "DZ",
          "AS",
          "AD",
          "AO",
          "AI",
          "AQ",
          "AG",
          "AR",
          "AM",
          "AW",
          "AU",
          "AT",
          "AZ",
          "BH",
          "BS",
          "BD",
          "BB",
          "BY",
          "BE",
          "BZ",
          "BJ",
          "BM",
          "BT",
          "BO",
          "BQ",
          "BA",
          "BW",
          "BV",
          "BR",
          "IO",
          "BN",
          "BG",
          "BF",
          "BI",
          "KH",
          "CM",
          "CA",
          "CV",
          "KY",
          "CF",
          "TD",
          "CL",
          "CN",
          "CX",
          "CC",
          "CO",
          "KM",
          "CG",
          "CD",
          "CK",
          "CR",
          "CI",
          "HR",
          "CU",
          "CW",
          "CY",
          "CZ",
          "DK",
          "DJ",
          "DM",
          "DO",
          "EC",
          "EG",
          "SV",
          "GQ",
          "ER",
          "EE",
          "ET",
          "FK",
          "FO",
          "FJ",
          "FI",
          "FR",
          "GF",
          "PF",
          "TF",
          "GA",
          "GM",
          "GE",
          "DE",
          "GH",
          "GI",
          "GR",
          "GL",
          "GD",
          "GP",
          "GU",
          "GT",
          "GG",
          "GN",
          "GW",
          "GY",
          "HT",
          "HM",
          "VA",
          "HN",
          "HK",
          "HU",
          "IS",
          "IN",
          "ID",
          "IR",
          "IQ",
          "IE",
          "IM",
          "IL",
          "IT",
          "JM",
          "JP",
          "JE",
          "JO",
          "KZ",
          "KE",
          "KI",
          "KP",
          "KR",
          "KW",
          "KG",
          "LA",
          "LV",
          "LB",
          "LS",
          "LR",
          "LY",
          "LI",
          "LT",
          "LU",
          "MO",
          "MK",
          "MG",
          "MW",
          "MY",
          "MV",
          "ML",
          "MT",
          "MH",
          "MQ",
          "MR",
          "MU",
          "YT",
          "MX",
          "FM",
          "MD",
          "MC",
          "MN",
          "ME",
          "MS",
          "MA",
          "MZ",
          "MM",
          "NA",
          "NR",
          "NP",
          "NL",
          "NC",
          "NZ",
          "NI",
          "NE",
          "NG",
          "NU",
          "NF",
          "MP",
          "NO",
          "OM",
          "PK",
          "PW",
          "PS",
          "PA",
          "PG",
          "PY",
          "PE",
          "PH",
          "PN",
          "PL",
          "PT",
          "PR",
          "QA",
          "RE",
          "RO",
          "RU",
          "RW",
          "BL",
          "SH",
          "KN",
          "LC",
          "MF",
          "PM",
          "VC",
          "WS",
          "SM",
          "ST",
          "SA",
          "SN",
          "RS",
          "SC",
          "SL",
          "SG",
          "SX",
          "SK",
          "SI",
          "SB",
          "SO",
          "ZA",
          "GS",
          "SS",
          "ES",
          "LK",
          "SD",
          "SR",
          "SJ",
          "SZ",
          "SE",
          "CH",
          "SY",
          "TW",
          "TJ",
          "TZ",
          "TH",
          "TL",
          "TG",
          "TK",
          "TO",
          "TT",
          "TN",
          "TR",
          "TM",
          "TC",
          "TV",
          "UG",
          "UA",
          "AE",
          "GB",
          "US",
          "UM",
          "UY",
          "UZ",
          "VU",
          "VE",
          "VN",
          "VG",
          "VI",
          "WF",
          "EH",
          "YE",
          "ZM",
          "ZW"
        ],
        "x-oapi-codegen-extra-tags": {
          "validate": "country,required"
        },
        "x-order": 11,
        "examples": [
          "US"
        ]
      },
      "address-reference-partial": {
        "type": "object",
        "title": "Partial Address Reference",
        "required": [
          ".tag",
          "postal_code"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "partial"
            ],
            "description": "The type of address reference",
            "x-order": 0,
            "examples": [
              "partial"
            ]
          },
          "postal_code": {
            "type": "string",
            "description": "The postal code associated with the credit card billing address.",
            "x-order": 1,
            "examples": [
              "94105"
            ]
          }
        }
      },
      "amount": {
        "type": "object",
        "description": "A monetary amount, i.e. a base unit amount and a supported currency.",
        "required": [
          "currency",
          "units"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "description": "A supported currency.",
            "enum": [
              "AUD",
              "CAD",
              "EUR",
              "GBP",
              "USD"
            ],
            "examples": [
              "USD"
            ]
          },
          "units": {
            "type": "integer",
            "description": "A monetary amount, represented in its base units (e.g. USD/EUR cents).",
            "format": "int64",
            "examples": [
              900
            ]
          }
        }
      },
      "cart-discount": {
        "required": [
          "amount"
        ],
        "type": "object",
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "code": {
            "type": "string",
            "description": "Discount code.",
            "maxLength": 1024,
            "examples": [
              "SUMMER10DISCOUNT"
            ]
          },
          "details_url": {
            "type": "string",
            "description": "Used to provide a link to additional details, such as a landing page, associated with the discount offering.",
            "maxLength": 8192,
            "format": "url",
            "examples": [
              "https://www.example.com/SUMMER-SALE"
            ]
          }
        }
      },
      "cart-item": {
        "type": "object",
        "required": [
          "name",
          "reference",
          "total_amount",
          "unit_price",
          "quantity"
        ],
        "properties": {
          "name": {
            "description": "The name of a given item.",
            "type": "string",
            "maxLength": 1024,
            "examples": [
              "Bolt Swag Bag"
            ]
          },
          "reference": {
            "type": "string",
            "description": "This value is used by Bolt as an external reference to a given item.",
            "maxLength": 1024,
            "examples": [
              "item_100"
            ]
          },
          "description": {
            "type": "string",
            "description": "A human-readable description of this cart item.",
            "examples": [
              "Large tote with Bolt logo."
            ]
          },
          "seller_id": {
            "type": "string",
            "description": "External reference ID for a marketplace seller.",
            "examples": [
              "seller_123"
            ]
          },
          "total_amount": {
            "$ref": "#/components/schemas/amount"
          },
          "unit_price": {
            "type": "integer",
            "description": "The item's unit price, i.e. the cost of a single item exclusive of tax and discounts.",
            "format": "int64",
            "examples": [
              1000
            ]
          },
          "quantity": {
            "type": "integer",
            "description": "The number of units that comprise this cart item.",
            "format": "int64",
            "maximum": 15000,
            "examples": [
              1
            ]
          },
          "image_url": {
            "type": "string",
            "description": "Used to provide a link to the image associated with the item.",
            "maxLength": 8192,
            "format": "url",
            "examples": [
              "https://www.example.com/products/123456/images/1.png"
            ]
          },
          "subscription_plan_id": {
            "type": "string",
            "description": "Subscription Plan ID that assigns this item to a specific subscription plan.",
            "maxLength": 1024,
            "examples": [
              "spl_123"
            ]
          }
        }
      },
      "payment-method-extended": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/payment-method-reference"
          },
          {
            "$ref": "#/components/schemas/payment-method-bolt-token"
          },
          {
            "$ref": "#/components/schemas/payment-method-credit-card"
          },
          {
            "$ref": "#/components/schemas/payment-method-applepay"
          },
          {
            "$ref": "#/components/schemas/payment-method-googlepay"
          },
          {
            "$ref": "#/components/schemas/payment-method-paypal"
          },
          {
            "$ref": "#/components/schemas/payment-method-affirm"
          },
          {
            "$ref": "#/components/schemas/payment-method-afterpay"
          },
          {
            "$ref": "#/components/schemas/payment-method-klarna"
          },
          {
            "$ref": "#/components/schemas/payment-method-klarna-account"
          },
          {
            "$ref": "#/components/schemas/payment-method-klarna-paynow"
          }
        ],
        "discriminator": {
          "propertyName": ".tag",
          "mapping": {
            "id": "#/components/schemas/payment-method-reference",
            "bolt_token": "#/components/schemas/payment-method-bolt-token",
            "credit_card": "#/components/schemas/payment-method-credit-card",
            "googlepay": "#/components/schemas/payment-method-googlepay",
            "applepay": "#/components/schemas/payment-method-applepay",
            "paypal": "#/components/schemas/payment-method-paypal",
            "affirm": "#/components/schemas/payment-method-affirm",
            "afterpay": "#/components/schemas/payment-method-afterpay",
            "klarna": "#/components/schemas/payment-method-klarna",
            "klarna_account": "#/components/schemas/payment-method-klarna-account",
            "klarna_paynow": "#/components/schemas/payment-method-klarna-paynow"
          }
        }
      },
      "payment-method-reference": {
        "type": "object",
        "required": [
          ".tag",
          "id"
        ],
        "title": "Payment by reference Method",
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "id"
            ],
            "examples": [
              "id"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "description": "Payment ID of the saved Bolt Payment method.",
            "examples": [
              "X5h6j8uLpVGK"
            ]
          }
        }
      },
      "payment-method-bolt-token": {
        "type": "object",
        "required": [
          ".tag",
          "token"
        ],
        "title": "Payment by Bolt Token Method",
        "description": "Pay with a saved card referenced by a Bolt token. The token is the value returned in the X-Bolt-Token response header when the card was added (requires the return_bolt_token division feature). No card details need to be re-supplied.",
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "bolt_token"
            ],
            "examples": [
              "bolt_token"
            ]
          },
          "token": {
            "type": "string",
            "description": "The Bolt token reference for the saved card.",
            "examples": [
              "019f0358-7f59-770b-8dc0-ccf6f711d1ac"
            ]
          }
        }
      },
      "payment-method-credit-card": {
        "title": "Credit Card Payment Method",
        "allOf": [
          {
            "type": "object",
            "required": [
              ".tag",
              "type",
              "billing_address"
            ],
            "properties": {
              ".tag": {
                "type": "string",
                "enum": [
                  "credit_card"
                ],
                "x-order": 0,
                "examples": [
                  "credit_card"
                ]
              },
              "id": {
                "type": "string",
                "format": "id",
                "readOnly": true,
                "x-order": 1,
                "examples": [
                  "X5h6j8uLpVGK"
                ]
              },
              "type": {
                "type": "string",
                "description": "The type of payment method",
                "x-order": 2,
                "examples": [
                  "credit_card"
                ]
              },
              "billing_address": {
                "$ref": "#/components/schemas/address-reference"
              }
            }
          },
          {
            "$ref": "#/components/schemas/credit-card"
          }
        ]
      },
      "credit-card": {
        "required": [
          "network",
          "bin",
          "last4",
          "expiration",
          "token"
        ],
        "type": "object",
        "properties": {
          "network": {
            "$ref": "#/components/schemas/credit-card-network"
          },
          "bin": {
            "type": "string",
            "description": "The Bank Identification Number (BIN). This is the first 4 to 8 digits of the account number.",
            "pattern": "^\\d+$",
            "examples": [
              "411111"
            ]
          },
          "last4": {
            "type": "string",
            "description": "The account number's last four digits.",
            "pattern": "^\\d{4}$",
            "examples": [
              "1004"
            ]
          },
          "expiration": {
            "type": "string",
            "description": "The expiration date, in YYYY-MM format.",
            "pattern": "^\\d{4}-\\d{2}$",
            "examples": [
              "2029-03"
            ]
          },
          "token": {
            "type": "string",
            "description": "The Bolt token associated with the credit card.",
            "writeOnly": true,
            "examples": [
              "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0"
            ]
          },
          "affirm_vcn_token": {
            "type": "string",
            "description": "The checkout token associated with Affirm VCN credit cards.",
            "examples": [
              "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0"
            ]
          },
          "default": {
            "type": "boolean",
            "description": "Indicates whether this credit card is the default payment method.",
            "examples": [
              true
            ]
          }
        }
      },
      "credit-card-network": {
        "type": "string",
        "description": "The credit card's network.",
        "enum": [
          "visa",
          "mastercard",
          "amex",
          "discover",
          "jcb",
          "dinersclub",
          "unionpay",
          "alliancedata",
          "citiplcc"
        ],
        "x-oapi-codegen-extra-tags": {
          "validate": "required"
        },
        "examples": [
          "visa"
        ]
      },
      "payment-method-applepay": {
        "title": "ApplePay Payment Method",
        "allOf": [
          {
            "type": "object",
            "required": [
              ".tag",
              "type"
            ],
            "properties": {
              ".tag": {
                "type": "string",
                "enum": [
                  "applepay"
                ],
                "x-order": 0,
                "examples": [
                  "applepay"
                ]
              },
              "id": {
                "type": "string",
                "format": "id",
                "readOnly": true,
                "x-order": 1,
                "examples": [
                  "X5h6j8uLpVGK"
                ]
              },
              "type": {
                "type": "string",
                "description": "The type of payment method",
                "x-order": 2,
                "examples": [
                  "applepay"
                ]
              },
              "billing_address": {
                "$ref": "#/components/schemas/address-reference"
              }
            }
          },
          {
            "$ref": "#/components/schemas/credit-card"
          },
          {
            "type": "object",
            "properties": {
              "bolt_reference": {
                "type": "string",
                "description": "Bolt generated Applepay token id needed for token life cycle management.",
                "examples": [
                  "a6f57b8c-3b12-4baf-9e77-0b9b2e3cb3d7"
                ]
              }
            }
          }
        ]
      },
      "payment-method-googlepay": {
        "title": "Googlepay Payment Method",
        "allOf": [
          {
            "type": "object",
            "required": [
              ".tag",
              "type"
            ],
            "properties": {
              ".tag": {
                "type": "string",
                "enum": [
                  "googlepay"
                ],
                "x-order": 0,
                "examples": [
                  "googlepay"
                ]
              },
              "id": {
                "type": "string",
                "format": "id",
                "readOnly": true,
                "x-order": 1,
                "examples": [
                  "X5h6j8uLpVGK"
                ]
              },
              "type": {
                "type": "string",
                "description": "The type of payment method",
                "x-order": 2,
                "examples": [
                  "googlepay"
                ]
              },
              "billing_address": {
                "$ref": "#/components/schemas/address-reference"
              }
            }
          },
          {
            "$ref": "#/components/schemas/credit-card"
          }
        ]
      },
      "payment-method-paypal": {
        "type": "object",
        "title": "PayPal Payment Method",
        "required": [
          ".tag",
          "success_url",
          "cancel_url"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "paypal"
            ],
            "x-order": 0,
            "examples": [
              "paypal"
            ]
          },
          "success_url": {
            "type": "string",
            "description": "Redirect URL for successful PayPal transaction.",
            "format": "url",
            "writeOnly": true,
            "examples": [
              "https://www.example.com/paypal-callback/success"
            ]
          },
          "cancel_url": {
            "type": "string",
            "description": "Redirect URL for canceled PayPal transaction.",
            "format": "url",
            "writeOnly": true,
            "examples": [
              "https://www.example.com/paypal-callback/cancel"
            ]
          }
        }
      },
      "payment-method-affirm": {
        "type": "object",
        "required": [
          ".tag",
          "return_url"
        ],
        "title": "Affirm Payment Method",
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "affirm"
            ],
            "examples": [
              "affirm"
            ]
          },
          "return_url": {
            "type": "string",
            "description": "Return URL to return to after payment completion in Affirm.",
            "format": "url",
            "writeOnly": true,
            "examples": [
              "https://www.example.com/handle_affirm_success"
            ]
          }
        }
      },
      "payment-method-afterpay": {
        "type": "object",
        "required": [
          ".tag",
          "return_url"
        ],
        "title": "Afterpay Payment Method",
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "afterpay"
            ],
            "examples": [
              "afterpay"
            ]
          },
          "return_url": {
            "type": "string",
            "description": "Return URL to return to after payment completion in Afterpay.",
            "format": "url",
            "writeOnly": true,
            "examples": [
              "https://www.example.com/handle_afterpay_success"
            ]
          }
        }
      },
      "payment-method-klarna": {
        "type": "object",
        "required": [
          ".tag",
          "return_url"
        ],
        "title": "Klarna Payment Method",
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "klarna"
            ],
            "examples": [
              "klarna"
            ]
          },
          "return_url": {
            "type": "string",
            "description": "Return URL to return to after payment completion in Klarna.",
            "format": "url",
            "writeOnly": true,
            "examples": [
              "https://www.example.com/handle_klarna_success"
            ]
          }
        }
      },
      "payment-method-klarna-account": {
        "type": "object",
        "required": [
          ".tag",
          "return_url"
        ],
        "title": "Klarna Account Payment Method",
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "klarna_account"
            ],
            "examples": [
              "klarna_account"
            ]
          },
          "return_url": {
            "type": "string",
            "description": "Return URL to return to after payment completion in Klarna.",
            "format": "url",
            "writeOnly": true,
            "examples": [
              "https://www.example.com/handle_klarna_account_success"
            ]
          }
        }
      },
      "payment-method-klarna-paynow": {
        "type": "object",
        "required": [
          ".tag",
          "return_url"
        ],
        "title": "Klarna Pay Now Payment Method",
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "klarna_paynow"
            ],
            "examples": [
              "klarna_paynow"
            ]
          },
          "return_url": {
            "type": "string",
            "description": "Return URL to return to after payment completion in Klarna.",
            "format": "url",
            "writeOnly": true,
            "examples": [
              "https://www.example.com/handle_klarna_paynow_success"
            ]
          }
        }
      },
      "seller-split": {
        "properties": {
          "amounts": {
            "$ref": "#/components/schemas/seller-split-amounts"
          },
          "marketplace_commission_fee": {
            "$ref": "#/components/schemas/marketplace-commission-fee"
          },
          "seller_id": {
            "type": "string",
            "examples": [
              "seller_12345"
            ]
          }
        },
        "type": "object"
      },
      "seller-split-amounts": {
        "properties": {
          "discount_total": {
            "format": "int64",
            "type": "integer",
            "examples": [
              100
            ]
          },
          "gross_total": {
            "format": "int64",
            "type": "integer",
            "examples": [
              1000
            ]
          },
          "merchant_subtotal": {
            "format": "int64",
            "type": "integer",
            "examples": [
              900
            ]
          },
          "shipping_total": {
            "format": "int64",
            "type": "integer",
            "examples": [
              100
            ]
          },
          "tax_total": {
            "format": "int64",
            "type": "integer",
            "examples": [
              100
            ]
          }
        },
        "type": "object"
      },
      "marketplace-commission-fee": {
        "properties": {
          "bps": {
            "format": "int64",
            "type": "integer",
            "examples": [
              100
            ]
          },
          "flat_cents": {
            "format": "int64",
            "type": "integer",
            "examples": [
              100
            ]
          },
          "metadata": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "type": "string"
            },
            "examples": [
              {
                "plan_type": "pro",
                "tier": "premium",
                "region": "us-east-1"
              }
            ]
          }
        },
        "type": "object"
      },
      "co-funding": {
        "type": "object",
        "required": [
          "amount",
          "reference"
        ],
        "properties": {
          "funder_public_id": {
            "type": "string",
            "description": "Public merchant ID of the merchant funding the payment. Set in Pattern B (funder initiates). Exactly one of funder_public_id or receiver_public_id must be present.",
            "examples": [
              "merchant_12345"
            ]
          },
          "receiver_public_id": {
            "type": "string",
            "description": "Public merchant ID of the merchant receiving the funding. Set in Pattern A (receiver initiates). Exactly one of funder_public_id or receiver_public_id must be present.",
            "examples": [
              "merchant_67890"
            ]
          },
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "Amount being funded in the smallest currency unit (cents for USD). Must be > 0 and amount + payment_method_amount = cart.total.amount.",
            "minimum": 1,
            "examples": [
              1000
            ]
          },
          "reference": {
            "type": "string",
            "description": "Idempotency reference for this co-funding transfer. Must be unique.",
            "examples": [
              "cof_12345_uuid"
            ]
          }
        }
      },
      "payment-response": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/payment-response-finalized"
          },
          {
            "$ref": "#/components/schemas/payment-response-pending"
          },
          {
            "$ref": "#/components/schemas/payment-response-three-ds-required"
          }
        ],
        "discriminator": {
          "propertyName": ".tag",
          "mapping": {
            "finalized": "#/components/schemas/payment-response-finalized",
            "pending": "#/components/schemas/payment-response-pending",
            "three_ds_required": "#/components/schemas/payment-response-three-ds-required"
          }
        }
      },
      "payment-response-finalized": {
        "type": "object",
        "required": [
          ".tag",
          "status",
          "transaction"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "finalized"
            ],
            "x-order": 0,
            "examples": [
              "finalized"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "x-order": 1,
            "examples": [
              "iKv7t5bgt1gg"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "success"
            ],
            "examples": [
              "success"
            ]
          },
          "transaction": {
            "$ref": "#/components/schemas/transaction"
          },
          "co_funding_summary": {
            "description": "Co-funding details for this payment, if co-funding was used.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/co-funding-summary"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "transaction": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "examples": [
              "OBYG-X1PX-FN55"
            ]
          },
          "authorizations": {
            "description": "Payment authorization events attached to a transaction",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/transaction-authorization"
            }
          }
        }
      },
      "transaction-authorization": {
        "type": "object",
        "properties": {
          "processor_reference": {
            "type": "string",
            "examples": [
              "123456789XYZ"
            ]
          },
          "processor_response": {
            "$ref": "#/components/schemas/processor-response"
          }
        }
      },
      "processor-response": {
        "description": "Raw authorization response from the payment processor",
        "properties": {
          "content_type": {
            "type": "string",
            "examples": [
              "application/json"
            ]
          },
          "api_version": {
            "type": "string",
            "examples": [
              "3.3"
            ]
          },
          "text": {
            "type": "string",
            "examples": [
              "<?xml version=\"1.0\" encoding=\"UTF-8\"?> <transaction> <id>bfraj39q</id> <status>authorized</status> <type>sale</type> <currency-iso-code>USD</currency-iso-code> <amount>57.71</amount> <amount-requested>57.71</amount-requested> <merchant-account-id>GenericMerchant</merchant-account-id> <order-id>ORDER123456</order-id> <created-at type=\"datetime\">2024-11-20T12:36:53Z</created-at> <updated-at type=\"datetime\">2024-11-20T12:36:54Z</updated-at> <customer> <first-name>John</first-name> <last-name>Doe</last-name> <email>example@example.com</email> <phone>1234567890</phone> <international-phone></international-phone> </customer> <billing> <first-name>John</first-name> <last-name>Doe</last-name> <street-address>123 Generic St</street-address> <locality>GenericCity</locality> <region>GenericRegion</region> <postal-code>12345</postal-code> <country-name>GenericCountry</country-name> <country-code-alpha2>GC</country-code-alpha2> <country-code-alpha3>GCR</country-code-alpha3> <country-code-numeric>999</country-code-numeric> <international-phone></international-phone> </billing> <refund-ids type=\"array\"></refund-ids> <partial-settlement-transaction-ids type=\"array\"></partial-settlement-transaction-ids> <shipping> <international-phone></international-phone> </shipping> <custom-fields></custom-fields> <account-funding-transaction type=\"boolean\">false</account-funding-transaction> <avs-postal-code-response-code>M</avs-postal-code-response-code> <avs-street-address-response-code>M</avs-street-address-response-code> <cvv-response-code>I</cvv-response-code> <processor-authorization-code>123456</processor-authorization-code> <processor-response-code>1000</processor-response-code> <processor-response-text>Approved</processor-response-text> <tax-exempt type=\"boolean\">false</tax-exempt> <processed-with-network-token type=\"boolean\">false</processed-with-network-token> <credit-card> <image-url>https://assets.braintreegateway.com/payment_method_logo/unknown.png?environment=production</image-url> <is-network-tokenized type=\"boolean\">false</is-network-tokenized> <prepaid>Unknown</prepaid> <healthcare>Unknown</healthcare> <debit>Unknown</debit> <durbin-regulated>Unknown</durbin-regulated> <commercial>Unknown</commercial> <payroll>Unknown</payroll> <issuing-bank>Unknown</issuing-bank> <country-of-issuance>Unknown</country-of-issuance> <product-id>Unknown</product-id> <venmo-sdk type=\"boolean\">false</venmo-sdk> </credit-card> <apple-pay> <prepaid>No</prepaid> <healthcare>Unknown</healthcare> <debit>No</debit> <durbin-regulated>Unknown</durbin-regulated> <commercial>No</commercial> <payroll>Unknown</payroll> <issuing-bank>GenericBank</issuing-bank> <country-of-issuance>GCR</country-of-issuance> <product-id>Unknown</product-id> <bin>411111</bin> <card-type>Apple Pay - GenericCard</card-type> <last-4>1234</last-4> <expiration-month>12</expiration-month> <expiration-year>2028</expiration-year> <image-url>https://assets.braintreegateway.com/payment_method_logo/apple_pay.png?environment=production</image-url> <payment-instrument-name>Card 1234</payment-instrument-name> <source-description>Card 1234</source-description> </apple-pay> <status-history type=\"array\"> <status-event> <timestamp type=\"datetime\">2024-11-20T12:36:54Z</timestamp> <status>authorized</status> <amount>57.71</amount> <transaction-source>api</transaction-source> </status-event> </status-history> <subscription></subscription> <add-ons type=\"array\"></add-ons> <discounts type=\"array\"></discounts> <descriptor></descriptor> <recurring type=\"boolean\">false</recurring> <channel></channel> <disbursement-details></disbursement-details> <disputes type=\"array\"></disputes> <authorization-adjustments type=\"array\"></authorization-adjustments> <payment-instrument-type>generic_card</payment-instrument-type> <processor-settlement-response-code></processor-settlement-response-code> <processor-settlement-response-text></processor-settlement-response-text> <network-transaction-id>123456789012345</network-transaction-id> <processor-response-type>approved</processor-response-type> <authorization-expires-at type=\"datetime\">2024-11-27T12:36:54Z</authorization-expires-at> <retry-ids type=\"array\"></retry-ids> <retried type=\"boolean\">false</retried> <refund-global-ids type=\"array\"></refund-global-ids> <partial-settlement-transaction-global-ids type=\"array\"></partial-settlement-transaction-global-ids> <global-id>generic_global_id</global-id> <retry-global-ids type=\"array\"></retry-global-ids> <retrieval-reference-number>123456789012345</retrieval-reference-number> <installments type=\"array\"></installments> <refunded-installments type=\"array\"></refunded-installments> <merchant-address></merchant-address> <pin-verified type=\"boolean\">false</pin-verified> <payment-receipt> <id>bfraj39q</id> <global-id>generic_global_id</global-id> <amount>57.71</amount> <currency-iso-code>USD</currency-iso-code> <processor-response-code>1000</processor-response-code> <processor-response-text>Approved</processor-response-text> <processor-authorization-code>123456</processor-authorization-code> <merchant-address></merchant-address> <type>sale</type> <pin-verified type=\"boolean\">false</pin-verified> </payment-receipt> </transaction>"
            ]
          }
        }
      },
      "co-funding-summary": {
        "type": "object",
        "required": [
          "funder_public_id",
          "receiver_public_id",
          "amount",
          "currency",
          "reference",
          "status"
        ],
        "properties": {
          "funder_public_id": {
            "type": "string",
            "description": "Public merchant ID of the merchant funding the payment.",
            "examples": [
              "merchant_12345"
            ]
          },
          "receiver_public_id": {
            "type": "string",
            "description": "Public merchant ID of the merchant receiving the funding.",
            "examples": [
              "merchant_67890"
            ]
          },
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "Amount being funded in the smallest currency unit (cents for USD).",
            "examples": [
              1000
            ]
          },
          "currency": {
            "type": "string",
            "description": "Currency code of the co-funding amount.",
            "pattern": "^[A-Z]{3}$",
            "examples": [
              "USD"
            ]
          },
          "reference": {
            "type": "string",
            "description": "Idempotency reference for this co-funding transfer.",
            "examples": [
              "cof_12345_uuid"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "submitted",
              "funded"
            ],
            "description": "Status of the co-funding transfer. 'pending' = created but not yet queued for funding, 'submitted' = queued in funding batch, 'funded' = settled.",
            "examples": [
              "pending"
            ]
          }
        }
      },
      "payment-response-pending": {
        "type": "object",
        "required": [
          ".tag",
          "status",
          "action",
          "url"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "pending"
            ],
            "x-order": 0,
            "examples": [
              "pending"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "x-order": 1,
            "examples": [
              "iKv7t5bgt1gg"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting_user_confirmation"
            ],
            "examples": [
              "awaiting_user_confirmation"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "redirect"
            ],
            "examples": [
              "redirect"
            ]
          },
          "url": {
            "type": "string",
            "format": "url",
            "examples": [
              "https://www.example.com/payments/finalize"
            ]
          }
        }
      },
      "payment-response-three-ds-required": {
        "type": "object",
        "required": [
          ".tag",
          "step_up_url",
          "jwt_payload"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "three_ds_required"
            ],
            "examples": [
              "three_ds_required"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "x-order": 1,
            "examples": [
              "iKv7t5bgt1gg"
            ]
          },
          "step_up_url": {
            "type": "string",
            "format": "url",
            "examples": [
              "https://www.example.com/payments/finalize"
            ]
          },
          "jwt_payload": {
            "type": "string",
            "examples": [
              "eyJ0cmFuc"
            ]
          }
        }
      },
      "error": {
        "type": "object",
        "required": [
          ".tag",
          "message"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "unauthorized",
              "forbidden",
              "unprocessable_request",
              "not_found"
            ],
            "description": "The type of error returned",
            "examples": [
              "unprocessable_request"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message, which might include information specific to the request that was made.",
            "examples": [
              "We were unable to process your request."
            ]
          }
        }
      },
      "field-error": {
        "type": "object",
        "description": "An error that pertains to validation of a specific field in the request.",
        "required": [
          ".tag",
          "message",
          "field"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "invalid_input_parameter"
            ],
            "description": "The type of error returned",
            "examples": [
              "invalid_input_parameter"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message, which might include information specific to the request that was made.",
            "examples": [
              "We were unable to process your request."
            ]
          },
          "field": {
            "type": "string",
            "description": "The field (in its hierarchical form) that is failing validation.",
            "examples": [
              "address.phone"
            ]
          }
        }
      },
      "three-ds-error": {
        "type": "object",
        "description": "An error that occurs during 3D Secure authentication or verification.",
        "required": [
          ".tag",
          "message"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "three_ds_authentication_failed",
              "three_ds_verification_failed",
              "three_ds_reference_missing"
            ],
            "description": "The type of 3DS error returned",
            "examples": [
              "three_ds_authentication_failed"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message about the 3DS failure.",
            "examples": [
              "3DS authentication with the card issuer failed"
            ]
          }
        }
      },
      "cart-error": {
        "type": "object",
        "required": [
          ".tag",
          "message"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "payment_already_exists",
              "currency_not_supported"
            ],
            "description": "The type of error returned",
            "examples": [
              "payment_already_exists"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message, which might include information specific to the request that was made.",
            "examples": [
              "A payment for this order already exists"
            ]
          }
        }
      },
      "credit-card-error": {
        "type": "object",
        "required": [
          ".tag",
          "message"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "declined",
              "declined_invalid_amount",
              "declined_invalid_cvv",
              "declined_invalid_merchant",
              "declined_invalid_number",
              "declined_expired",
              "declined_call_issuer",
              "declined_unsupported"
            ],
            "description": "The type of error returned",
            "examples": [
              "declined_invalid_cvv"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message, which might include information specific to the request that was made.",
            "examples": [
              "The payment was declined because the CVV is not valid"
            ]
          }
        }
      }
    },
    "examples": {
      "payment-initialize-payment-method-reference": {
        "summary": "Payment using an existing payment method saved on the account",
        "value": {
          "cart": {
            "total": {
              "units": 9000,
              "currency": "USD"
            },
            "tax": {
              "units": 100,
              "currency": "USD"
            },
            "order_reference": "order_100",
            "order_description": "Order #1234567890",
            "display_id": "215614191",
            "items": [
              {
                "name": "Bolt Swag Bag",
                "reference": "item_100",
                "description": "Large tote with Bolt logo.",
                "total_amount": {
                  "units": 9000,
                  "currency": "USD"
                },
                "unit_price": 1000,
                "quantity": 9,
                "image_url": "https://www.example.com/products/123456/images/1.png"
              }
            ],
            "shipments": [
              {
                "cost": {
                  "units": 10000,
                  "currency": "USD"
                },
                "carrier": "FedEx",
                "address": {
                  ".tag": "id",
                  "id": "D4g3h5tBuVYK9"
                }
              }
            ],
            "discounts": [
              {
                "amount": {
                  "units": 10000,
                  "currency": "USD"
                },
                "code": "SUMMER10DISCOUNT",
                "details_url": "https://www.example.com/SUMMER-SALE"
              }
            ]
          },
          "payment_method": {
            ".tag": "id",
            "id": "X5h6j8uLpVGK"
          }
        }
      },
      "payment-initialize-payment-method-credit-card": {
        "summary": "Payment using a credit card",
        "value": {
          "cart": {
            "total": {
              "units": 9000,
              "currency": "USD"
            },
            "tax": {
              "units": 100,
              "currency": "USD"
            },
            "order_reference": "order_100",
            "order_description": "Order #1234567890",
            "display_id": "215614191",
            "items": [
              {
                "name": "Bolt Swag Bag",
                "reference": "item_100",
                "description": "Large tote with Bolt logo.",
                "total_amount": {
                  "units": 9000,
                  "currency": "USD"
                },
                "unit_price": 1000,
                "quantity": 9,
                "image_url": "https://www.example.com/products/123456/images/1.png"
              }
            ],
            "shipments": [
              {
                "cost": {
                  "units": 10000,
                  "currency": "USD"
                },
                "carrier": "FedEx",
                "address": {
                  ".tag": "explicit",
                  "first_name": "Alice",
                  "last_name": "Baker",
                  "street_address1": "535 Mission St, Ste 1401",
                  "locality": "San Francisco",
                  "postal_code": "94105",
                  "region": "CA",
                  "country_code": "US"
                }
              }
            ],
            "discounts": [
              {
                "amount": {
                  "units": 10000,
                  "currency": "USD"
                },
                "code": "SUMMER10DISCOUNT",
                "details_url": "https://www.example.com/SUMMER-SALE"
              }
            ]
          },
          "payment_method": {
            ".tag": "credit_card",
            "type": "credit",
            "network": "visa",
            "bin": "411111",
            "last4": "1004",
            "expiration": "2025-03",
            "token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",
            "billing_address": {
              ".tag": "explicit",
              "first_name": "Alice",
              "last_name": "Baker",
              "street_address1": "535 Mission St, Ste 1401",
              "locality": "San Francisco",
              "postal_code": "94105",
              "region": "CA",
              "country_code": "US"
            }
          },
          "authorization_type": "final",
          "auto_capture": true
        }
      },
      "payment-initialize-payment-method-paypal": {
        "summary": "Payment using a PayPal account",
        "value": {
          "cart": {
            "total": {
              "units": 9000,
              "currency": "USD"
            },
            "tax": {
              "units": 100,
              "currency": "USD"
            },
            "order_reference": "order_100",
            "order_description": "Order #1234567890",
            "display_id": "215614191",
            "items": [
              {
                "name": "Bolt Swag Bag",
                "reference": "item_100",
                "description": "Large tote with Bolt logo.",
                "total_amount": {
                  "units": 9000,
                  "currency": "USD"
                },
                "unit_price": 1000,
                "quantity": 9,
                "image_url": "https://www.example.com/products/123456/images/1.png"
              }
            ],
            "shipments": [
              {
                "cost": {
                  "units": 10000,
                  "currency": "USD"
                },
                "carrier": "FedEx",
                "address": {
                  ".tag": "explicit",
                  "first_name": "Alice",
                  "last_name": "Baker",
                  "street_address1": "535 Mission St, Ste 1401",
                  "locality": "San Francisco",
                  "postal_code": "94105",
                  "region": "CA",
                  "country_code": "US"
                }
              }
            ],
            "discounts": [
              {
                "amount": {
                  "units": 10000,
                  "currency": "USD"
                },
                "code": "SUMMER10DISCOUNT",
                "details_url": "https://www.example.com/SUMMER-SALE"
              }
            ]
          },
          "payment_method": {
            ".tag": "paypal",
            "success_url": "https://www.example.com/paypal-callback/success",
            "cancel_url": "https://www.example.com/paypal-callback/cancel"
          }
        }
      },
      "payment-response-finalized": {
        "summary": "The payment is final and a transaction record has been created",
        "value": {
          ".tag": "finalized",
          "id": "iKv7t5bgt1gg",
          "status": "success",
          "transaction": {
            "reference": "OBYG-X1PX-FN55",
            "authorizations": [
              {
                "processor_reference": "123456789XYZ"
              }
            ]
          }
        }
      },
      "payment-response-pending": {
        "summary": "The payment is pending and further action is required",
        "value": {
          ".tag": "pending",
          "id": "iKv7t5bgt1gg",
          "status": "awaiting_user_confirmation",
          "action": "redirect",
          "url": "https://www.paypal.com/checkout/redirect"
        }
      }
    },
    "responses": {
      "response-payment-error": {
        "description": "The payment operation cannot complete",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/error"
                },
                {
                  "$ref": "#/components/schemas/field-error"
                },
                {
                  "$ref": "#/components/schemas/three-ds-error"
                },
                {
                  "$ref": "#/components/schemas/cart-error"
                },
                {
                  "$ref": "#/components/schemas/credit-card-error"
                }
              ]
            },
            "examples": {
              "missing-input": {
                "summary": "A required field is missing",
                "value": {
                  ".tag": "invalid_input_parameter",
                  "message": "cart is required",
                  "field": "cart"
                }
              },
              "invalid-cart": {
                "summary": "The operation could not be completed because the cart fails validation",
                "value": {
                  ".tag": "payment_already_exists",
                  "message": "A payment for this order already exists"
                }
              },
              "invalid-credit-card": {
                "summary": "The credit card payment method could not be added because it was declined",
                "value": {
                  ".tag": "declined_invalid_cvv",
                  "message": "The payment was declined because the CVV is not valid"
                }
              },
              "three-ds-authentication-failed": {
                "summary": "3DS Cardinal authentication failed",
                "value": {
                  ".tag": "three_ds_authentication_failed",
                  "message": "3DS Cardinal authentication failed"
                }
              },
              "three-ds-verification-failed": {
                "summary": "3DS verification check failed",
                "value": {
                  ".tag": "three_ds_verification_failed",
                  "message": "3DS verification failed"
                }
              },
              "three-ds-reference-missing": {
                "summary": "3DS reference is missing in the request",
                "value": {
                  ".tag": "three_ds_reference_missing",
                  "message": "3DS reference is missing in the request"
                }
              }
            }
          }
        }
      },
      "response-default": {
        "description": "An error has occurred, and no further details are provided (e.g. 5xx errors)"
      }
    },
    "securitySchemes": {
      "api-key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "oauth": {
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "/v1/oauth/authorize",
            "refreshUrl": "/v1/oauth/token",
            "tokenUrl": "/v1/oauth/token",
            "scopes": {
              "bolt.account.manage": "This scope grants permissions to perform read/edit/delete actions on Bolt Account data",
              "bolt.account.view": "This scope grants permissions to perform read only actions on Bolt Account data",
              "openid": "This scope grants permissions that enable Bolt Single Sign-On (SSO) by granting a JSON Web Token (JWT) that stores account data."
            }
          }
        },
        "type": "oauth2"
      }
    }
  }
}
```