Bolt Financial Callbacks API

openapi: 3.2.0
info:
  version: 3.3.22
  title: Bolt API Reference Callbacks API
  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
tags:
- name: Callbacks
  description: Implement Callback endpoints on your servers to power Bolt experiences. Different Bolt packages require different callbacks to be implemented. Consult your relevant product documentation for a list of required callbacks.
paths:
  /callbacks/accounts:
    post:
      x-speakeasy-ignore: true
      summary: Callback to update or create a full shopper account
      operationId: callbackAccountUpsert
      description: Create or update a shopper account with profile information, payment and addresses. This is also known as the "upsert account" API, a combination of update and insert.
      tags:
      - Callbacks
      security: []
      parameters:
      - $ref: '#/components/parameters/x-bolt-hmac-sha256'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-full-account'
      responses:
        '200':
          description: The account details were successfully created/updated
        4XX:
          description: An error has occurred, and further details are contained in the response.
        default:
          description: An error has occurred, and further details are contained in the response.
components:
  parameters:
    x-bolt-hmac-sha256:
      description: A Bolt-signed hash-based message authentication code (HMAC) to verify that the sender is Bolt.
      in: header
      name: X-Bolt-Hmac-Sha256
      required: true
      schema:
        type: string
  schemas:
    payment-method-klarna:
      type: object
      required:
      - .tag
      - return_url
      title: Klarna Payment Method
      properties:
        .tag:
          type: string
          enum:
          - klarna
          example: klarna
        return_url:
          type: string
          description: Return URL to return to after payment completion in Klarna.
          format: url
          writeOnly: true
          example: https://www.example.com/handle_klarna_success
    payment-method-afterpay:
      type: object
      required:
      - .tag
      - return_url
      title: Afterpay Payment Method
      properties:
        .tag:
          type: string
          enum:
          - afterpay
          example: afterpay
        return_url:
          type: string
          description: Return URL to return to after payment completion in Afterpay.
          format: url
          writeOnly: true
          example: https://www.example.com/handle_afterpay_success
    payment-method-affirm:
      type: object
      required:
      - .tag
      - return_url
      title: Affirm Payment Method
      properties:
        .tag:
          type: string
          enum:
          - affirm
          example: affirm
        return_url:
          type: string
          description: Return URL to return to after payment completion in Affirm.
          format: url
          writeOnly: true
          example: https://www.example.com/handle_affirm_success
    payment-method-applepay:
      title: ApplePay Payment Method
      allOf:
      - type: object
        required:
        - .tag
        - type
        properties:
          .tag:
            type: string
            enum:
            - applepay
            example: applepay
            x-order: 0
          id:
            type: string
            format: id
            readOnly: true
            example: X5h6j8uLpVGK
            x-order: 1
          type:
            type: string
            description: The type of payment method
            example: applepay
            x-order: 2
          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.
            example: a6f57b8c-3b12-4baf-9e77-0b9b2e3cb3d7
    payment-method:
      oneOf:
      - $ref: '#/components/schemas/payment-method-credit-card'
      - $ref: '#/components/schemas/payment-method-googlepay'
      - $ref: '#/components/schemas/payment-method-applepay'
      - $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:
          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-googlepay:
      title: Googlepay Payment Method
      allOf:
      - type: object
        required:
        - .tag
        - type
        properties:
          .tag:
            type: string
            enum:
            - googlepay
            example: googlepay
            x-order: 0
          id:
            type: string
            format: id
            readOnly: true
            example: X5h6j8uLpVGK
            x-order: 1
          type:
            type: string
            description: The type of payment method
            example: googlepay
            x-order: 2
          billing_address:
            $ref: '#/components/schemas/address-reference'
      - $ref: '#/components/schemas/credit-card'
    payment-method-klarna-paynow:
      type: object
      required:
      - .tag
      - return_url
      title: Klarna Pay Now Payment Method
      properties:
        .tag:
          type: string
          enum:
          - klarna_paynow
          example: klarna_paynow
        return_url:
          type: string
          description: Return URL to return to after payment completion in Klarna.
          format: url
          writeOnly: true
          example: https://www.example.com/handle_klarna_paynow_success
    address-listing:
      type: object
      description: An address saved on an account, i.e. a physical address plus any additional account-specific metadata.
      required:
      - first_name
      - last_name
      - street_address1
      - locality
      - postal_code
      - country_code
      properties:
        id:
          type: string
          format: id
          description: The address's unique identifier.
          readOnly: true
          example: D4g3h5tBuVYK9
          x-order: 1
        first_name:
          type: string
          description: The first name of the person associated with this address.
          example: Alice
          x-order: 2
        last_name:
          type: string
          description: The last name of the person associated with this address.
          example: Baker
          x-order: 3
        company:
          type: string
          description: The company associated with this address.
          example: ACME Corporation
          x-order: 4
        street_address1:
          type: string
          description: The street address associated with this address.
          example: 535 Mission St, Ste 1401
          x-order: 5
        street_address2:
          type: string
          description: Any additional, optional, street address information associated with this address.
          example: c/o Shipping Department
          x-order: 6
        locality:
          type: string
          description: The locality (e.g. city, town, etc...) associated with this address.
          example: San Francisco
          x-order: 7
        postal_code:
          type: string
          description: The postal code associated with this address.
          example: '94105'
          x-order: 8
        region:
          type: string
          description: The region or administrative area (e.g. state, province, county, etc...) associated with this address.
          example: CA
          x-order: 9
        country_code:
          $ref: '#/components/schemas/country-code'
        email:
          type: string
          format: email
          description: The email address associated with this address.
          example: alice@example.com
          x-order: 11
        phone:
          type: string
          format: phone
          description: The phone number associated with this address.
          example: '+14155550199'
          x-oapi-codegen-extra-tags:
            validate: phone=strict
          x-order: 12
        is_default:
          type: boolean
          description: Whether or not this is the default address saved.
          readOnly: true
          example: true
    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
          example: explicit
          x-order: 0
        id:
          type: string
          format: id
          description: The address's unique identifier.
          readOnly: true
          example: D4g3h5tBuVYK9
          x-order: 1
        first_name:
          type: string
          description: The first name of the person associated with this address.
          example: Alice
          x-order: 2
        last_name:
          type: string
          description: The last name of the person associated with this address.
          example: Baker
          x-order: 3
        company:
          type: string
          description: The company associated with this address.
          example: ACME Corporation
          x-order: 4
        street_address1:
          type: string
          description: The street address associated with this address.
          example: 535 Mission St, Ste 1401
          x-order: 5
        street_address2:
          type: string
          description: Any additional, optional, street address information associated with this address.
          example: c/o Shipping Department
          x-order: 6
        locality:
          type: string
          description: The locality (e.g. city, town, etc...) associated with this address.
          example: San Francisco
          x-order: 7
        postal_code:
          type: string
          description: The postal code associated with this address.
          example: '94105'
          x-order: 8
        region:
          type: string
          description: The region or administrative area (e.g. state, province, county, etc...) associated with this address.
          example: CA
          x-order: 9
        country_code:
          $ref: '#/components/schemas/country-code'
        email:
          type: string
          format: email
          description: The email address associated with this address.
          example: alice@example.com
          x-order: 11
        phone:
          type: string
          format: phone
          description: The phone number associated with this address.
          example: '+14155550199'
          x-order: 12
    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
      example: US
      x-oapi-codegen-extra-tags:
        validate: country,required
      x-order: 11
    payment-method-credit-card:
      title: Credit Card Payment Method
      allOf:
      - type: object
        required:
        - .tag
        - type
        - billing_address
        properties:
          .tag:
            type: string
            enum:
            - credit_card
            example: credit_card
            x-order: 0
          id:
            type: string
            format: id
            readOnly: true
            example: X5h6j8uLpVGK
            x-order: 1
          type:
            type: string
            description: The type of payment method
            example: credit_card
            x-order: 2
          billing_address:
            $ref: '#/components/schemas/address-reference'
      - $ref: '#/components/schemas/credit-card'
    profile:
      type: object
      description: An account's identifying information.
      required:
      - first_name
      - last_name
      - email
      properties:
        first_name:
          type: string
          description: The given name of the person associated with this profile.
          example: Alice
          x-order: 1
        last_name:
          type: string
          description: The last name of the person associated with this profile.
          example: Baker
          x-order: 2
        email:
          type: string
          format: email
          description: The email address asscoiated with this profile.
          example: alice@example.com
          x-order: 3
        phone:
          type: string
          format: phone
          description: The phone number associated with this profile.
          example: '+14155550199'
          x-order: 4
    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
          example: partial
          x-order: 0
        postal_code:
          type: string
          description: The postal code associated with the credit card billing address.
          example: '94105'
          x-order: 1
    credit-card-network:
      type: string
      description: The credit card's network.
      enum:
      - visa
      - mastercard
      - amex
      - discover
      - jcb
      - dinersclub
      - unionpay
      - alliancedata
      - citiplcc
      example: visa
      x-oapi-codegen-extra-tags:
        validate: required
    create-full-account:
      type: object
      properties:
        account_details:
          $ref: '#/components/schemas/account'
        customer_data_id:
          type: string
          description: A unique identifier for this account on your cart platform.
          example: 5FEB9028D
    account:
      type: object
      required:
      - addresses
      - payment_methods
      properties:
        addresses:
          type: array
          description: A list of addresses associated with this account. These can be considered the "shipping addresses". The account's visible addresses are filtered according to the configured shipping destinations in your Bolt merchant dashboard. If no account addresses are available, use the billing address of the selected payment method.
          items:
            $ref: '#/components/schemas/address-listing'
        payment_methods:
          type: array
          description: A list of payment methods associated with this account. The account's visible payment methods are filtered to include only cards that are chargeable.
          items:
            $ref: '#/components/schemas/payment-method'
        profile:
          $ref: '#/components/schemas/profile'
    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+$
          example: '411111'
        last4:
          type: string
          description: The account number's last four digits.
          pattern: ^\d{4}$
          example: '1004'
        expiration:
          type: string
          description: The expiration date, in YYYY-MM format.
          pattern: ^\d{4}-\d{2}$
          example: 2029-03
        token:
          type: string
          description: The Bolt token associated with the credit card.
          writeOnly: true
          example: a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0
        affirm_vcn_token:
          type: string
          description: The checkout token associated with Affirm VCN credit cards.
          example: a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0
        default:
          type: boolean
          description: Indicates whether this credit card is the default payment method.
          example: true
    address-reference-id:
      type: object
      title: Address ID Reference
      required:
      - .tag
      - id
      properties:
        .tag:
          type: string
          enum:
          - id
          description: The type of address reference
          example: id
        id:
          type: string
          format: id
          description: The address's ID
          example: D4g3h5tBuVYK9
    payment-method-paypal:
      type: object
      title: PayPal Payment Method
      required:
      - .tag
      - success_url
      - cancel_url
      properties:
        .tag:
          type: string
          enum:
          - paypal
          example: paypal
          x-order: 0
        success_url:
          type: string
          description: Redirect URL for successful PayPal transaction.
          format: url
          writeOnly: true
          example: https://www.example.com/paypal-callback/success
        cancel_url:
          type: string
          description: Redirect URL for canceled PayPal transaction.
          format: url
          writeOnly: true
          example: https://www.example.com/paypal-callback/cancel
    payment-method-klarna-account:
      type: object
      required:
      - .tag
      - return_url
      title: Klarna Account Payment Method
      properties:
        .tag:
          type: string
          enum:
          - klarna_account
          example: klarna_account
        return_url:
          type: string
          description: Return URL to return to after payment completion in Klarna.
          format: url
          writeOnly: true
          example: https://www.example.com/handle_klarna_account_success
    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'
  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