Visa B2B Connect API API

openapi: 3.2.0
info:
  title: Visa B2B Connect B2B Connect API
  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
servers:
- url: https://sandbox.api.visa.com
  description: Sandbox Server
- url: https://api.visa.com
  description: Production Server
security:
- mutualTLS: []
tags:
- name: B2B Connect API
  description: Initiate, track, and manage large-value cross-border B2B payment transactions with direct settlement capabilities.
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:
  schemas:
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description
    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
    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
    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
  securitySchemes:
    mutualTLS:
      type: mutualTLS
      description: Two-way SSL mutual authentication using a PKI certificate issued by Visa.
externalDocs:
  description: Visa B2B Connect Documentation
  url: https://developer.visa.com/capabilities/vba/docs