asyncapi: 3.0.0
info:
  title: CentaPay callbacks
  version: 1.0.0
  description: >-
    Callbacks the CentaPay platform sends to a merchant endpoint for the S2S CARD API.


    Generated from the OpenAPI specification at https://www.centapay.com/openapi.yaml, so the two

    cannot disagree about a field. Nothing here is maintained by hand.


    The callback is the authoritative outcome of a payment. The synchronous response is not.


    Delivery behaviour, retry schedule and verification are documented in prose at

    https://www.centapay.com/docs/operations and
    https://www.centapay.com/docs/operations/troubleshooting, and are

    deliberately not encoded here as protocol bindings.
  contact:
    name: CentaPay support
    email: support@centapay.com
channels:
  merchantCallbackUrl:
    address: '{callbackUrl}'
    title: Merchant callback URL
    description: >-
      The URL configured on the account, not per request. A callback_url sent as a request parameter
      on a server-to-server operation is ignored.
    parameters:
      callbackUrl:
        description: The HTTPS endpoint registered for the account. Maximum 255 characters.
    messages:
      ExtendedCallbackData:
        $ref: '#/components/messages/ExtendedCallbackData'
      SaleCallbackSuccess:
        $ref: '#/components/messages/SaleCallbackSuccess'
      SaleCallbackDeclined:
        $ref: '#/components/messages/SaleCallbackDeclined'
      SaleCallbackRedirect:
        $ref: '#/components/messages/SaleCallbackRedirect'
      SaleCallbackUndefined:
        $ref: '#/components/messages/SaleCallbackUndefined'
      CaptureCallbackSuccess:
        $ref: '#/components/messages/CaptureCallbackSuccess'
      CaptureCallbackDeclined:
        $ref: '#/components/messages/CaptureCallbackDeclined'
      CaptureCallbackUndefined:
        $ref: '#/components/messages/CaptureCallbackUndefined'
      CreditvoidCallbackSuccess:
        $ref: '#/components/messages/CreditvoidCallbackSuccess'
      CreditvoidCallbackDeclined:
        $ref: '#/components/messages/CreditvoidCallbackDeclined'
      CreditvoidCallbackUndefined:
        $ref: '#/components/messages/CreditvoidCallbackUndefined'
      VoidCallbackSuccess:
        $ref: '#/components/messages/VoidCallbackSuccess'
      VoidCallbackDeclined:
        $ref: '#/components/messages/VoidCallbackDeclined'
      VoidCallbackUndefined:
        $ref: '#/components/messages/VoidCallbackUndefined'
      Credit2CardCallbackSuccess:
        $ref: '#/components/messages/Credit2CardCallbackSuccess'
      Credit2CardCallbackDeclined:
        $ref: '#/components/messages/Credit2CardCallbackDeclined'
      Credit2CardCallbackUndefined:
        $ref: '#/components/messages/Credit2CardCallbackUndefined'
      RetryCallbackSuccess:
        $ref: '#/components/messages/RetryCallbackSuccess'
      RetryCallbackDeclined:
        $ref: '#/components/messages/RetryCallbackDeclined'
operations:
  receiveCallback:
    action: receive
    channel:
      $ref: '#/channels/merchantCallbackUrl'
    title: Receive a transaction callback
    description: The merchant endpoint receives this. Respond 200 to acknowledge.
    messages:
      - $ref: '#/channels/merchantCallbackUrl/messages/ExtendedCallbackData'
      - $ref: '#/channels/merchantCallbackUrl/messages/SaleCallbackSuccess'
      - $ref: '#/channels/merchantCallbackUrl/messages/SaleCallbackDeclined'
      - $ref: '#/channels/merchantCallbackUrl/messages/SaleCallbackRedirect'
      - $ref: '#/channels/merchantCallbackUrl/messages/SaleCallbackUndefined'
      - $ref: '#/channels/merchantCallbackUrl/messages/CaptureCallbackSuccess'
      - $ref: '#/channels/merchantCallbackUrl/messages/CaptureCallbackDeclined'
      - $ref: '#/channels/merchantCallbackUrl/messages/CaptureCallbackUndefined'
      - $ref: '#/channels/merchantCallbackUrl/messages/CreditvoidCallbackSuccess'
      - $ref: '#/channels/merchantCallbackUrl/messages/CreditvoidCallbackDeclined'
      - $ref: '#/channels/merchantCallbackUrl/messages/CreditvoidCallbackUndefined'
      - $ref: '#/channels/merchantCallbackUrl/messages/VoidCallbackSuccess'
      - $ref: '#/channels/merchantCallbackUrl/messages/VoidCallbackDeclined'
      - $ref: '#/channels/merchantCallbackUrl/messages/VoidCallbackUndefined'
      - $ref: '#/channels/merchantCallbackUrl/messages/Credit2CardCallbackSuccess'
      - $ref: '#/channels/merchantCallbackUrl/messages/Credit2CardCallbackDeclined'
      - $ref: '#/channels/merchantCallbackUrl/messages/Credit2CardCallbackUndefined'
      - $ref: '#/channels/merchantCallbackUrl/messages/RetryCallbackSuccess'
      - $ref: '#/channels/merchantCallbackUrl/messages/RetryCallbackDeclined'
components:
  messages:
    ExtendedCallbackData:
      name: ExtendedCallbackData
      title: Extended Callback Data
      contentType: application/x-www-form-urlencoded
      summary: Present only if "Add Extended Data to Callback" is enabled for the account.
      payload:
        type: object
        properties:
          connector_name:
            type: string
            description: Payment gateway name
          rrn:
            type: string
            description: Retrieval Reference Number
          approval_code:
            type: string
          gateway_id:
            type: string
          extra_gateway_id:
            type: string
          merchant_name:
            type: string
          mid_name:
            type: string
          issuer_country:
            type: string
          issuer_bank:
            type: string
    SaleCallbackSuccess:
      name: SaleCallbackSuccess
      title: Sale Callback Success
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          connector_name:
            type: string
            description: Payment gateway name
          rrn:
            type: string
            description: Retrieval Reference Number
          approval_code:
            type: string
          gateway_id:
            type: string
          extra_gateway_id:
            type: string
          merchant_name:
            type: string
          mid_name:
            type: string
          issuer_country:
            type: string
          issuer_bank:
            type: string
          action:
            type: string
            enum:
              - SALE
              - RECURRING_SALE
          result:
            const: SUCCESS
          status:
            type: string
            enum:
              - PENDING
              - PREPARE
              - SETTLED
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          descriptor:
            type: string
          amount:
            type: string
          currency:
            type: string
          card:
            type: string
            description: 'Masked PAN, e.g. 411111****1111. For wallets: decrypted token PAN.'
          card_expiration_date:
            type: string
          recurring_token:
            type: string
            description: If `recurring_init=Y` was sent.
          schedule_id:
            type: string
            description: If a schedule was used.
          card_token:
            type: string
            description: If `req_token=Y` was sent.
          exchange_rate:
            type: string
            description: FX rate if currency conversion applied.
          exchange_rate_base:
            type: string
            description: Base rate if double conversion.
          exchange_currency:
            type: string
            description: Original currency.
          exchange_amount:
            type: string
            description: Original amount.
          custom_data:
            type: object
            additionalProperties: true
            description: Echoed from request.
          digital_wallet:
            type: string
            enum:
              - googlepay
              - applepay
          pan_type:
            type: string
            enum:
              - DPAN
              - FPAN
          hash:
            type: string
            description: Validate with Formula 2.
    SaleCallbackDeclined:
      name: SaleCallbackDeclined
      title: Sale Callback Declined
      contentType: application/x-www-form-urlencoded
      summary: >-
        Does NOT include card, card_expiration_date, descriptor, amount, currency, card_token, or
        recurring_token.
      payload:
        type: object
        properties:
          action:
            type: string
            enum:
              - SALE
              - RECURRING_SALE
          result:
            const: DECLINED
          status:
            const: DECLINED
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          decline_reason:
            type: string
          custom_data:
            type: object
            additionalProperties: true
          digital_wallet:
            type: string
          pan_type:
            type: string
          hash:
            type: string
    SaleCallbackRedirect:
      name: SaleCallbackRedirect
      title: Sale Callback Redirect
      contentType: application/x-www-form-urlencoded
      summary: WAITING event - 3DS verification pending. Does NOT include card or card_expiration_date.
      payload:
        type: object
        properties:
          action:
            const: SALE
          result:
            const: REDIRECT
          status:
            type: string
            enum:
              - 3DS
              - REDIRECT
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          descriptor:
            type: string
          amount:
            type: string
          currency:
            type: string
          redirect_url:
            type: string
          redirect_params:
            oneOf:
              - type: object
                additionalProperties: true
              - type: array
              - type: 'null'
          redirect_method:
            type: string
            enum:
              - POST
              - GET
          custom_data:
            type: object
            additionalProperties: true
          digital_wallet:
            type: string
          pan_type:
            type: string
          hash:
            type: string
    SaleCallbackUndefined:
      name: SaleCallbackUndefined
      title: Sale Callback Undefined
      contentType: application/x-www-form-urlencoded
      summary: Does NOT include card or card_expiration_date.
      payload:
        type: object
        properties:
          action:
            type: string
            enum:
              - SALE
              - RECURRING_SALE
          result:
            const: UNDEFINED
          status:
            type: string
            enum:
              - PENDING
              - PREPARE
              - SETTLED
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          descriptor:
            type: string
          amount:
            type: string
          currency:
            type: string
          custom_data:
            type: object
            additionalProperties: true
          digital_wallet:
            type: string
          pan_type:
            type: string
          hash:
            type: string
    CaptureCallbackSuccess:
      name: CaptureCallbackSuccess
      title: Capture Callback Success
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          connector_name:
            type: string
            description: Payment gateway name
          rrn:
            type: string
            description: Retrieval Reference Number
          approval_code:
            type: string
          gateway_id:
            type: string
          extra_gateway_id:
            type: string
          merchant_name:
            type: string
          mid_name:
            type: string
          issuer_country:
            type: string
          issuer_bank:
            type: string
          action:
            const: CAPTURE
          result:
            const: SUCCESS
          status:
            const: SETTLED
          order_id:
            type: string
          trans_id:
            type: string
          amount:
            type: string
          trans_date:
            type: string
          descriptor:
            type: string
          currency:
            type: string
          hash:
            type: string
            description: Validate with Formula 2.
    CaptureCallbackDeclined:
      name: CaptureCallbackDeclined
      title: Capture Callback Declined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: CAPTURE
          result:
            const: DECLINED
          status:
            const: PENDING
          order_id:
            type: string
          trans_id:
            type: string
          decline_reason:
            type: string
          hash:
            type: string
    CaptureCallbackUndefined:
      name: CaptureCallbackUndefined
      title: Capture Callback Undefined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: CAPTURE
          result:
            const: UNDEFINED
          status:
            const: PENDING
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          descriptor:
            type: string
          amount:
            type: string
          currency:
            type: string
          hash:
            type: string
    CreditvoidCallbackSuccess:
      name: CreditvoidCallbackSuccess
      title: Creditvoid Callback Success
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          connector_name:
            type: string
            description: Payment gateway name
          rrn:
            type: string
            description: Retrieval Reference Number
          approval_code:
            type: string
          gateway_id:
            type: string
          extra_gateway_id:
            type: string
          merchant_name:
            type: string
          mid_name:
            type: string
          issuer_country:
            type: string
          issuer_bank:
            type: string
          action:
            const: CREDITVOID
          result:
            const: SUCCESS
          status:
            type: string
            enum:
              - REFUND
              - REVERSAL
              - SETTLED
            description: REFUND/REVERSAL for full; SETTLED remains for partial refund.
          order_id:
            type: string
          trans_id:
            type: string
          creditvoid_date:
            type: string
          amount:
            type: string
          hash:
            type: string
            description: Validate with Formula 2.
    CreditvoidCallbackDeclined:
      name: CreditvoidCallbackDeclined
      title: Creditvoid Callback Declined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: CREDITVOID
          result:
            const: DECLINED
          order_id:
            type: string
          trans_id:
            type: string
          decline_reason:
            type: string
          hash:
            type: string
    CreditvoidCallbackUndefined:
      name: CreditvoidCallbackUndefined
      title: Creditvoid Callback Undefined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: CREDITVOID
          result:
            const: UNDEFINED
          status:
            const: SETTLED
          order_id:
            type: string
          trans_id:
            type: string
          creditvoid_date:
            type: string
          amount:
            type: string
          hash:
            type: string
    VoidCallbackSuccess:
      name: VoidCallbackSuccess
      title: Void Callback Success
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          connector_name:
            type: string
            description: Payment gateway name
          rrn:
            type: string
            description: Retrieval Reference Number
          approval_code:
            type: string
          gateway_id:
            type: string
          extra_gateway_id:
            type: string
          merchant_name:
            type: string
          mid_name:
            type: string
          issuer_country:
            type: string
          issuer_bank:
            type: string
          action:
            const: VOID
          result:
            const: SUCCESS
          status:
            const: VOID
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          hash:
            type: string
            description: Void signature - md5(strtoupper(strrev(trans_id)) . PASSWORD).
    VoidCallbackDeclined:
      name: VoidCallbackDeclined
      title: Void Callback Declined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: VOID
          result:
            const: DECLINED
          status:
            const: SETTLED
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          decline_reason:
            type: string
          hash:
            type: string
            description: Void signature - md5(strtoupper(strrev(trans_id)) . PASSWORD).
    VoidCallbackUndefined:
      name: VoidCallbackUndefined
      title: Void Callback Undefined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: VOID
          result:
            const: UNDEFINED
          status:
            type: string
            enum:
              - PENDING
              - SETTLED
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          hash:
            type: string
            description: Void signature - md5(strtoupper(strrev(trans_id)) . PASSWORD).
    Credit2CardCallbackSuccess:
      name: Credit2CardCallbackSuccess
      title: Credit2Card Callback Success
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          connector_name:
            type: string
            description: Payment gateway name
          rrn:
            type: string
            description: Retrieval Reference Number
          approval_code:
            type: string
          gateway_id:
            type: string
          extra_gateway_id:
            type: string
          merchant_name:
            type: string
          mid_name:
            type: string
          issuer_country:
            type: string
          issuer_bank:
            type: string
          action:
            const: CREDIT2CARD
          result:
            const: SUCCESS
          status:
            const: SETTLED
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          hash:
            type: string
            description: Validate with Formula 6.
    Credit2CardCallbackDeclined:
      name: Credit2CardCallbackDeclined
      title: Credit2Card Callback Declined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: CREDIT2CARD
          result:
            const: DECLINED
          status:
            const: DECLINED
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          decline_reason:
            type: string
          hash:
            type: string
    Credit2CardCallbackUndefined:
      name: Credit2CardCallbackUndefined
      title: Credit2Card Callback Undefined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: CREDIT2CARD
          result:
            const: UNDEFINED
          status:
            const: PREPARE
          order_id:
            type: string
          trans_id:
            type: string
          trans_date:
            type: string
          hash:
            type: string
    RetryCallbackSuccess:
      name: RetryCallbackSuccess
      title: Retry Callback Success
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: RETRY
          result:
            const: SUCCESS
          status:
            const: SETTLED
          order_id:
            type: string
          trans_id:
            type: string
          amount:
            type: string
          currency:
            type: string
          hash:
            type: string
            description: Validate with Formula 2.
    RetryCallbackDeclined:
      name: RetryCallbackDeclined
      title: Retry Callback Declined
      contentType: application/x-www-form-urlencoded
      payload:
        type: object
        properties:
          action:
            const: RETRY
          result:
            const: DECLINED
          status:
            const: DECLINED
          order_id:
            type: string
          trans_id:
            type: string
          amount:
            type: string
          currency:
            type: string
          decline_reason:
            type: string
          hash:
            type: string