Visa B2B Connect

openapi: 3.1.0
info:
  title: Visa B2B Connect
  description: >-
    The Visa B2B Connect API provides direct settlement capabilities for
    large-value business-to-business cross-border transactions. Built on Visa's
    core payments infrastructure with distributed ledger technology, B2B Connect
    helps financial institutions and their clients overcome costly processes and
    geographic barriers for international B2B payments.
  version: '1'
  contact:
    name: Visa Developer Support
    url: https://developer.visa.com/support
  termsOfService: https://developer.visa.com/capabilities/vba/product-terms
externalDocs:
  description: Visa B2B Connect Documentation
  url: https://developer.visa.com/capabilities/vba/docs
servers:
  - url: https://sandbox.api.visa.com
    description: Sandbox Server
  - url: https://api.visa.com
    description: Production Server
tags:
  - name: B2B Connect API
    description: >-
      Initiate, track, and manage large-value cross-border B2B payment
      transactions with direct settlement capabilities.
security:
  - mutualTLS: []
paths:
  /vba/v1/payments:
    post:
      operationId: initiatePayment
      summary: Initiate Payment
      description: >-
        Initiates a new cross-border B2B payment transaction. The payment is
        routed through Visa's network for direct settlement between the
        originating and beneficiary financial institutions.
      tags:
        - B2B Connect API
      requestBody:
        description: Payment initiation details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInitiationRequest'
      responses:
        '201':
          description: Payment initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInitiationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
  /vba/v1/payments/{paymentId}:
    get:
      operationId: getPaymentStatus
      summary: Get Payment Status
      description: >-
        Retrieves the current status and details of a B2B Connect payment
        transaction.
      tags:
        - B2B Connect API
      parameters:
        - name: paymentId
          in: path
          required: true
          description: Unique identifier for the payment
          schema:
            type: string
      responses:
        '200':
          description: Payment status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatusResponse'
        '401':
          description: Unauthorized
        '404':
          description: Payment not found
  /vba/v1/payments/{paymentId}/acknowledge:
    post:
      operationId: acknowledgePayment
      summary: Acknowledge Payment
      description: >-
        Acknowledges receipt of a B2B Connect payment by the beneficiary
        financial institution.
      tags:
        - B2B Connect API
      parameters:
        - name: paymentId
          in: path
          required: true
          description: Unique identifier for the payment
          schema:
            type: string
      responses:
        '200':
          description: Payment acknowledged successfully
        '401':
          description: Unauthorized
        '404':
          description: Payment not found
components:
  securitySchemes:
    mutualTLS:
      type: mutualTLS
      description: >-
        Two-way SSL mutual authentication using a PKI certificate issued by
        Visa.
  schemas:
    PaymentInitiationRequest:
      type: object
      required:
        - originatorBIC
        - beneficiaryBIC
        - amount
        - currency
        - originatorReference
      properties:
        originatorBIC:
          type: string
          description: SWIFT BIC code of the originating financial institution
          pattern: '^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$'
        beneficiaryBIC:
          type: string
          description: SWIFT BIC code of the beneficiary financial institution
          pattern: '^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$'
        amount:
          type: number
          format: double
          description: Payment amount
        currency:
          type: string
          description: ISO 4217 currency code
          pattern: '^[A-Z]{3}$'
        originatorReference:
          type: string
          description: Originator's unique reference for the payment
        originatorName:
          type: string
          description: Name of the originating party
        beneficiaryName:
          type: string
          description: Name of the beneficiary party
        beneficiaryAccountNumber:
          type: string
          description: Account number of the beneficiary
        purposeOfPayment:
          type: string
          description: Purpose or reason for the payment
        valueDate:
          type: string
          format: date
          description: Requested settlement date
    PaymentInitiationResponse:
      type: object
      properties:
        paymentId:
          type: string
          description: Unique identifier assigned to the payment
        status:
          type: string
          description: Current payment status
          enum:
            - INITIATED
            - PROCESSING
            - SETTLED
            - REJECTED
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the payment was created
    PaymentStatusResponse:
      type: object
      properties:
        paymentId:
          type: string
          description: Unique identifier for the payment
        status:
          type: string
          description: Current payment status
          enum:
            - INITIATED
            - PROCESSING
            - SETTLED
            - REJECTED
            - ACKNOWLEDGED
        originatorBIC:
          type: string
          description: SWIFT BIC of the originator
        beneficiaryBIC:
          type: string
          description: SWIFT BIC of the beneficiary
        amount:
          type: number
          format: double
          description: Payment amount
        currency:
          type: string
          description: Payment currency
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the payment was created
        settledAt:
          type: string
          format: date-time
          description: Timestamp when the payment was settled
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description