Blackbaud Checkout API

openapi: 3.2.0
info:
  title: 'Blackbaud SKY API: Payments Checkout API'
  description: This API enables users to accept and manage payments via Blackbaud Merchant Services.
  version: '1.0'
  x-apievangelist-provenance:
    source: https://developer.sky.blackbaud.com/developer/apis/payments
    method: assembled from Blackbaud's public API Management developer data API (operations, parameters, representations, examples, stored definitions); nothing authored
    assembled: '2026-10-14'
servers:
- url: https://api.sky.blackbaud.com/payments
security:
- Bb-Api-Subscription-Key: []
  OAuth2: []
tags:
- name: Checkout
paths:
  /v1/checkout/publickey:
    get:
      operationId: GetPublicKey
      summary: Public key
      description: Gets the client's public key. See the Blackbaud Checkout integration guide to learn more.
      responses:
        '200':
          description: Returned when the operation is successful. The response body contains the client's public key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeyRead'
              example:
                public_key: 48b58ad0-b763-49b5-95f1-78fb91627f6a
        '404':
          description: Returned when the public key is not found. The response body contains error details.
      tags:
      - Checkout
  /v1/checkout/securitytoken/{payment_configuration_id}:
    get:
      operationId: GetSecurityToken
      summary: Security token
      description: Gets the security token and the amount of time (in seconds) before the token is set to expire
      parameters:
      - name: payment_configuration_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the payment configuration to be used to process this request.
      responses:
        '200':
          description: Returned when the operation is successful. The response body contains the security token and the amount of time (in seconds) before the token is set to expire.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityTokenRead'
              example:
                expires_in: 1000
                security_token: 48b58ad0-b763-49b5-95f1-78fb91627f6a
        '404':
          description: Returned when the security token is not found. The response body contains error details.
      tags:
      - Checkout
  /v1/checkout/transaction:
    post:
      operationId: CreateCheckoutTransaction
      summary: Checkout transaction
      description: Creates a transaction that has been previously authorized by Blackbaud Checkout. See the Blackbaud Checkout integration guide to learn more.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutTransactionAdd'
            example:
              amount: 1000
              authorization_token: 992c159f-dcca-4495-aa33-1025546c7af2
              application_fee: 100
        description: The transaction information to charge.
      responses:
        '200':
          description: Returned when the operation is successful. The response body contains transaction details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRead'
              example:
                additional_fee: 25
                amount: 1000
                net_amount: 925
                application: Payments API
                billing_info:
                  city: Charleston
                  country: US
                  post_code: '29492'
                  state: SC
                  street: 2000 Daniel Island Drive
                comment: Recurring donation
                credit_card:
                  card_type: Visa
                  exp_month: 2
                  exp_year: 1985
                  last_four: '1111'
                  name: Blackbaud
                  pay_pal_funding_source: Unknown
                currency: USD
                disbursement_status: NotDisbursable
                donor_ip_address: 192.168.0.1
                fraud_result:
                  anonymous_proxy_result: NotProcessed
                  bin_and_ip_country_result: NotProcessed
                  high_risk_country_result: NotProcessed
                  result_code: NotProcessed
                  risk_score: 0
                  risk_threshold: 0
                  velocity_result: NotProcessed
                id: 92844827-5b74-40db-907f-480b13242eb5
                related_transactions:
                - id: 6fef1d90-60f2-43ea-aa96-b7562286c57d
                  transaction_type: Refund
                is_live: false
                state: Processed
                token: 00000000-0000-0000-0000-000000000000
                transaction_date: '2018-01-31T11:07:12Z'
                transaction_type: CardNotPresent
                total_fees: 75
                authorization_code: '123456'
                transaction_category: donation
                gateway_result:
                  message: Gateway declined
        '400':
          description: Returned when the request body is not in the appropriate format. The response body contains error details.
        '404':
          description: Returned when the specified transaction is not found. The response body contains error details.
        '409':
          description: Returned when the request is received while the transaction is currently being processed. The response body contains error details.
        '201':
          description: Returned when the transaction is successfully charged but full details can’t be retrieved. The response body is null.
      tags:
      - Checkout
  /v1/checkout/transactions/{authorization_token}:
    get:
      operationId: GetCheckoutTransaction
      summary: Checkout transaction
      description: Returns information about a transaction that has been previously authorized by Blackbaud Checkout.
      parameters:
      - name: authorization_token
        in: path
        required: true
        schema:
          type: string
        description: The authorization token of the transaction for which you would like to retrieve additional information.
      responses:
        '200':
          description: Returned when the operation is successful. The response body contains transaction details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRead'
              example:
                additional_fee: 25
                amount: 1000
                net_amount: 925
                application: Payments API
                billing_info:
                  city: Charleston
                  country: US
                  post_code: '29492'
                  state: SC
                  street: 2000 Daniel Island Drive
                comment: Recurring donation
                credit_card:
                  card_type: Visa
                  exp_month: 2
                  exp_year: 1985
                  last_four: '1111'
                  name: Blackbaud
                  pay_pal_funding_source: Unknown
                currency: USD
                disbursement_status: NotDisbursable
                donor_ip_address: 192.168.0.1
                fraud_result:
                  anonymous_proxy_result: NotProcessed
                  bin_and_ip_country_result: NotProcessed
                  high_risk_country_result: NotProcessed
                  result_code: NotProcessed
                  risk_score: 0
                  risk_threshold: 0
                  velocity_result: NotProcessed
                id: 92844827-5b74-40db-907f-480b13242eb5
                related_transactions:
                - id: 6fef1d90-60f2-43ea-aa96-b7562286c57d
                  transaction_type: Refund
                is_live: false
                state: Processed
                token: 00000000-0000-0000-0000-000000000000
                transaction_date: '2018-01-31T11:07:12Z'
                transaction_type: CardNotPresent
                total_fees: 75
                authorization_code: '123456'
                transaction_category: donation
                gateway_result:
                  message: Gateway declined
        '400':
          description: Returned when the request body is not in the appropriate format. The response body contains error details.
        '404':
          description: Returned when the specified transaction is not found. The response body contains error details.
      tags:
      - Checkout
components:
  schemas:
    CreditCardRead:
      type: object
      properties:
        card_type:
          type:
          - string
          - 'null'
          description: The IIN value of the card.
        exp_month:
          type: integer
          description: The expiration month for the card.
          format: int32
        exp_year:
          type: integer
          description: The expiration year for the card.
          format: int32
        last_four:
          type:
          - string
          - 'null'
          description: The last 4 digits of primary account number for this card.
        name:
          type:
          - string
          - 'null'
          description: The name of the card holder.
        pay_pal_funding_source:
          $ref: '#/components/schemas/PayPalFundingSource'
      additionalProperties: false
      description: The information of the credit card for the transaction.
    GatewayResultRead:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
          description: A message provided by the gateway that processed this transaction. Requires a direct debit return id passed in.
      additionalProperties: false
      description: The gateway result information for the transaction.
    TransactionState:
      enum:
      - Unknown
      - Processed
      - Failed
      - Refunded
      - Pending
      - Authorized
      - Voided
      - Created
      type: string
      description: The current processing state of the transaction.<p>Available values:</p><ul><li><i>Unknown</i></li><li><i>Processed</i></li><li><i>Failed</i></li><li><i>Refunded</i></li><li><i>Pending</i></li><li><i>Authorized</i></li><li><i>Voided</i></li><li><i>Created</i></li></ul>
    FraudResultRead:
      type: object
      properties:
        anonymous_proxy_result:
          type:
          - string
          - 'null'
          description: 'Used for clients who have opted in to Premium Fraud Service, this is the result of the anonymous proxy validation.

            The possible values are NotProcessed, Pass, or Failed.'
        bin_and_ip_country_result:
          type:
          - string
          - 'null'
          description: 'Used for clients who have opted in to Premium Fraud Service, this is the result of the bin origination country compared to the origination country of the ip.

            The possible values are NotProcessed, Pass, or Failed.'
        high_risk_country_result:
          type:
          - string
          - 'null'
          description: 'Used for clients who have opted in to Premium Fraud Service, this is the result of the high risk country validation.

            The possible values are NotProcessed, Pass, or Failed.'
        result_code:
          type:
          - string
          - 'null'
          description: 'Used for clients who have opted in to Premium Fraud Service, this is the result of the overall result of the premium fraud validation.

            The possible values are NotProcessed, Passed, FailedProcessingError, FailedProfileSettings, MissingRequiredLicensekey, MissingRequiredField, or NonRoutableIP'
        risk_score:
          type: integer
          description: Used for clients who have opted in to Premium Fraud Service, this is the score that was determined for this transaction.
          format: int32
        risk_threshold:
          type: integer
          description: Used for clients who have opted in to Premium Fraud Service, this is the threshold that was set by the client at the time of this transaction.
          format: int32
        velocity_result:
          type:
          - string
          - 'null'
          description: 'Used for clients who have opted in to Premium Fraud Service, this is the result of the velocity validation.

            The possible values are NotProcessed, Pass, or Failed.'
      additionalProperties: false
      description: The fraud result information for the transaction.
    CheckoutTransactionAdd:
      required:
      - amount
      - authorization_token
      type: object
      properties:
        amount:
          type: integer
          description: 'The amount to charge. Measured in cents: 1000 = $10.00.'
          format: int32
        authorization_token:
          type: string
          description: The authorization token of the transaction to charge.
          format: uuid
        application_fee:
          type: integer
          description: 'The custom fee associated with the Checkout transaction. Measured in cents: 100 = $1.00.

            If the fee exceeds the maximum threshold, then the capture fails, and you must <a href="https://developer.sky.blackbaud.com/docs/services/payments/operations/CreateRefund">void the authorization</a> or try again with a smaller fee.'
          format: int32
      additionalProperties: false
      description: Defines the data model for post checkout transaction request.
    SecurityTokenRead:
      type: object
      properties:
        expires_in:
          type: integer
          description: The amount of time (in seconds) before the token is set to expire.
          format: int32
        security_token:
          type: string
          description: Gets the security token
          format: uuid
      additionalProperties: false
      description: Defines the data model for the Security Token endpoint response.
    GrantRead:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: The source of the grant
        id:
          type:
          - string
          - 'null'
          description: The id of the created grant
        daf_pay_details:
          $ref: '#/components/schemas/DAFPayDetails'
      additionalProperties: false
      description: Grant Read Details
    RelatedTransactionRead:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The unique identifier of this related transaction.
        transaction_type:
          type:
          - string
          - 'null'
          description: "The transaction type of this related transaction. \nPossible values are Refund, DirectDebitRefund, DirectDebitReturn, ChargeBack, ReverseChargeback, or Adjustment."
      additionalProperties: false
      description: Represents a related transaction.
    TransactionRead:
      type: object
      properties:
        account_type:
          type:
          - string
          - 'null'
          description: 'The type of account of this transaction. Used for Direct Debit transactions.

            Possible values are Checking, Savings, Corporate checkings, or Corporate savings.'
        additional_fee:
          type: integer
          description: 'The additional fee amount for this transaction.

            Measured in cents: 1000 = $10.00.'
          format: int32
        amount:
          type: integer
          description: 'The gross amount of this transaction. Measured in cents: 1000 = $10.00.'
          format: int32
        net_amount:
          type: integer
          description: 'The net amount of this transaction after fees. Measured in cents: 1000 = $10.00.'
          format: int32
        application:
          type:
          - string
          - 'null'
          description: The calling Application of this transaction.
        billing_info:
          $ref: '#/components/schemas/BillingInfoRead'
        check_number:
          type:
          - string
          - 'null'
          description: The Check Number for the transaction to be processed.
        comment:
          type:
          - string
          - 'null'
          description: The comment on this transaction.
        credit_card:
          $ref: '#/components/schemas/CreditCardRead'
        currency:
          type:
          - string
          - 'null'
          description: The 3 char ISO4217 currency code used for this transaction.
        disbursement_status:
          type:
          - string
          - 'null'
          description: 'The disbursement status of this transaction.

            Possible values are Disbursable, DoNotDisburse, and Disbursed.'
        donor_ip_address:
          type:
          - string
          - 'null'
          description: The routable IPv4 address where this transaction originated.
        email_address:
          type:
          - string
          - 'null'
          description: The account holder’s email address.
        fraud_result:
          $ref: '#/components/schemas/FraudResultRead'
        id:
          type: string
          description: The unique identifier of this transaction.
          format: uuid
        reference_transaction_id:
          type:
          - string
          - 'null'
          description: 'The unique identifier of the original transaction associated with a refund or dispute.

            Present when the specified transaction_id is a refund, dispute, or direct debit return.'
          format: uuid
        related_transactions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/RelatedTransactionRead'
          description: An array of related transactions for this transaction.
        is_live:
          type: boolean
          description: True if this is not a test or demo transaction.
          x-bb-suppressions:
          - parameter_property_name
        pending_date:
          type:
          - string
          - 'null'
          description: The date by which decision could be made for the transaction. It will be approved or declined.
        phone_number:
          type:
          - string
          - 'null'
          description: The account holder’s phone number.
        routing_number:
          type:
          - string
          - 'null'
          description: The Routing Number for the transaction.
        state:
          $ref: '#/components/schemas/TransactionState'
        terminal_type:
          type:
          - string
          - 'null'
          description: 'Used for card present transactions to indicate the type of terminal used.

            Possible values are Unknown, AutomatedDispensingMachine, SelfServiceTerminal, LimitedAmountTerminal, MobilePayDevice, ChipAndPIN, or VerifoneP400'
        token:
          type: string
          description: The stored token. Available only on creation of Transaction record.
          format: uuid
        transaction_date:
          type:
          - string
          - 'null'
          description: The date and time of this transaction.
        transaction_type:
          type:
          - string
          - 'null'
          description: "The transaction type of this transaction. \nPossible values are CardNotPresent, CardPresent, DirectDebit, TransactionBatch, DirectDebitBatch, OfflineBatch, Refund, DirectDebitRefund, ChargeBack, or DirectDebitReturn."
        application_fee:
          type:
          - integer
          - 'null'
          description: 'The application fee amount for this transaction.

            Measured in cents: 1000 = $10.00.'
          format: int32
        total_fees:
          type: integer
          description: 'The total fees for this transaction.

            Measured in cents: 1000 = $10.00.'
          format: int32
        authorization_code:
          type:
          - string
          - 'null'
          description: The authorization code for the transaction.
        transaction_category:
          type:
          - string
          - 'null'
          description: 'The category for this transaction (ex: "donation").'
        pay_pal_reference_id:
          type:
          - string
          - 'null'
          description: A reference number from PayPal for the transaction.
        gateway_result:
          $ref: '#/components/schemas/GatewayResultRead'
        grant_read:
          $ref: '#/components/schemas/GrantRead'
      additionalProperties: false
      description: Represents a created transaction.
    PublicKeyRead:
      type: object
      properties:
        public_key:
          type: string
          description: Gets the public key
          format: uuid
      additionalProperties: false
      description: Defines the data model for the Public Key endpoint response.
    BillingInfoRead:
      type: object
      properties:
        city:
          type:
          - string
          - 'null'
          description: The account holder’s billing city.
        country:
          type:
          - string
          - 'null'
          description: The account holder’s billing country - ISO standard.
        post_code:
          type:
          - string
          - 'null'
          description: The account holder’s billing postal code.
        state:
          type:
          - string
          - 'null'
          description: The account holder’s billing state - ISO standard.
        street:
          type:
          - string
          - 'null'
          description: The account holder’s billing address.
      additionalProperties: false
      description: The billing info for the transaction.
    PayPalFundingSource:
      enum:
      - Unknown
      - PayPal
      - Venmo
      type: string
      description: The type of PayPal funding source, if any, used to determine the PayPal payment source used for the transaction.<p>Available values:</p><ul><li><i>Unknown</i></li><li><i>PayPal</i></li><li><i>Venmo</i></li></ul>
    DAFPayDetails:
      type: object
      properties:
        tracking_id:
          type:
          - string
          - 'null'
          description: A 10-digit alphanumeric identifier generated by DAFpay, included in the initial grant request and usually passed to the nonprofit from the DAF.
        external_grant_id:
          type:
          - string
          - 'null'
          description: A string identifier generated by the DAF provider following a successful grant initiation request.
      additionalProperties: false
      description: DAF Pay Details
  securitySchemes:
    Bb-Api-Subscription-Key:
      type: apiKey
      name: Bb-Api-Subscription-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.blackbaud.com/oauth/authorize
          tokenUrl: https://oauth2.sky.blackbaud.com/token
          scopes: {}