Tamara Full BNPL Lifecycle

arazzo: 1.0.1
info:
  title: Tamara Full BNPL Lifecycle
  summary: Create a checkout session, confirm approval, authorise, and capture in one flow.
  description: >-
    Walks a Tamara order through the full happy-path online BNPL lifecycle in a
    single workflow: create a hosted checkout session, read the resulting order to
    confirm Tamara approved it, authorise the approved order, and finally capture
    funds on fulfilment. When the order is not approved the flow ends before
    authorising. Every step spells out its request inline so the flow can be read
    and executed without opening the underlying OpenAPI descriptions.
  version: 1.0.0
sourceDescriptions:
- name: checkoutApi
  url: ../openapi/tamara-checkout-api-openapi.yml
  type: openapi
- name: ordersApi
  url: ../openapi/tamara-orders-api-openapi.yml
  type: openapi
- name: paymentsApi
  url: ../openapi/tamara-payments-api-openapi.yml
  type: openapi
workflows:
- workflowId: full-bnpl-lifecycle
  summary: Create, approve-check, authorise, and capture a Tamara order end to end.
  description: >-
    Creates a checkout session, retrieves the order, authorises it when approved,
    and captures the supplied amount against the authorised order.
  inputs:
    type: object
    required:
    - merchantToken
    - orderReferenceId
    - totalAmount
    - description
    - countryCode
    - paymentType
    - items
    - consumer
    - shippingAddress
    - taxAmount
    - shippingAmount
    - merchantUrl
    - captureAmount
    - shippingInfo
    properties:
      merchantToken:
        type: string
        description: Tamara-issued merchant API bearer token.
      orderReferenceId:
        type: string
        description: The merchant's own reference id for the order.
      totalAmount:
        type: object
        description: Money object with amount and currency for the order total.
      description:
        type: string
        description: Short description of the order (max 256 chars).
      countryCode:
        type: string
        description: Two-letter country code (SA, AE, BH, KW, OM).
      paymentType:
        type: string
        description: PAY_BY_INSTALMENTS or PAY_NOW.
      items:
        type: array
        description: Line items in the order.
        items:
          type: object
      consumer:
        type: object
        description: Consumer first_name, last_name, phone_number and optional details.
      shippingAddress:
        type: object
        description: Shipping address for the order.
      taxAmount:
        type: object
        description: Money object for the total tax amount.
      shippingAmount:
        type: object
        description: Money object for the shipping amount.
      merchantUrl:
        type: object
        description: Merchant success/failure/cancel redirect URLs.
      captureAmount:
        type: object
        description: Money object (amount + currency) to capture on fulfilment.
      shippingInfo:
        type: object
        description: Shipping info (shipped_at, shipping_company, tracking_number, tracking_url).
  steps:
  - stepId: createSession
    description: >-
      Create a hosted checkout session so Tamara can collect payment and complete
      the BNPL or Pay-Now flow with the consumer.
    operationId: createCheckoutSession
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.merchantToken"
    requestBody:
      contentType: application/json
      payload:
        order_reference_id: $inputs.orderReferenceId
        total_amount: $inputs.totalAmount
        description: $inputs.description
        country_code: $inputs.countryCode
        payment_type: $inputs.paymentType
        items: $inputs.items
        consumer: $inputs.consumer
        shipping_address: $inputs.shippingAddress
        tax_amount: $inputs.taxAmount
        shipping_amount: $inputs.shippingAmount
        merchant_url: $inputs.merchantUrl
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      orderId: $response.body#/order_id
      checkoutUrl: $response.body#/checkout_url
  - stepId: getOrder
    description: >-
      Read the order Tamara created so the workflow can confirm it is approved
      before authorising and capturing.
    operationId: getOrderDetails
    parameters:
    - name: order_id
      in: path
      value: $steps.createSession.outputs.orderId
    - name: Authorization
      in: header
      value: "Bearer $inputs.merchantToken"
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      orderStatus: $response.body#/status
    onSuccess:
    - name: orderApproved
      type: goto
      stepId: authorise
      criteria:
      - context: $response.body
        condition: $.status == "approved"
        type: jsonpath
    - name: orderNotApproved
      type: end
      criteria:
      - context: $response.body
        condition: $.status != "approved"
        type: jsonpath
  - stepId: authorise
    description: >-
      Transition the approved order to authorised so funds can be captured.
    operationId: authoriseOrder
    parameters:
    - name: order_id
      in: path
      value: $steps.createSession.outputs.orderId
    - name: Authorization
      in: header
      value: "Bearer $inputs.merchantToken"
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      authorisedStatus: $response.body#/status
      authorizedAmount: $response.body#/authorized_amount
  - stepId: capture
    description: >-
      Perform a full or partial capture against the authorised order, confirming
      shipment or fulfilment of items to the customer.
    operationId: captureOrder
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.merchantToken"
    requestBody:
      contentType: application/json
      payload:
        order_id: $steps.createSession.outputs.orderId
        total_amount: $inputs.captureAmount
        shipping_info: $inputs.shippingInfo
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      captureId: $response.body#/capture_id
      captureStatus: $response.body#/status
      capturedAmount: $response.body#/captured_amount
  outputs:
    orderId: $steps.createSession.outputs.orderId
    checkoutUrl: $steps.createSession.outputs.checkoutUrl
    authorisedStatus: $steps.authorise.outputs.authorisedStatus
    captureId: $steps.capture.outputs.captureId
    captureStatus: $steps.capture.outputs.captureStatus