openapi: 3.1.0
info:
  title: Payment modifications
  version: "1"
  description: Refund, capture, adjust the amount of, or reverse the authorisation
    of an existing payment.
tags:
  - name: Payment modifications
    description: Refund, capture, adjust or reverse an existing payment.
paths:
  /api2.php?action=refund:
    servers:
      - url: https://sandbox-payments.datmanpay.com
        description: Sandbox
      - url: https://payments.datmanpay.com
        description: Production
    post:
      operationId: refundPayment
      summary: Refund a payment
      description: >-
        Refunds all or part of a payment, identified by your `order_id` and the
        `merchant_id`. The refund can't be more than what's left to refund on
        the payment. If the payment was only authorised (a pre-auth), it is
        captured in full first and then refunded.


        **Errors are returned with HTTP 200.** Check `outcome` in the body: it
        is `success` or `failed`, and `message` explains a failure. This
        includes an invalid or missing `api_token`.
      tags:
        - Payment modifications
      security:
        - ApiTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefundRequest"
            examples:
              refund:
                summary: Partial refund to card
                value:
                  merchant_id: "663412"
                  order_id: "100245"
                  amount: 10.5
                  reason: Item out of stock
              refundWithSplit:
                summary: Refund with split refunds
                value:
                  merchant_id: "663412"
                  order_id: "100246"
                  amount: 20
                  reason: Order cancelled
                  refund_split_fee:
                    - partner_merchant_id: 663500
                      refund_amount: 3.5
      responses:
        "200":
          description: The refund result (`outcome` is `success`), or why it failed
            (`outcome` is `failed`).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/RefundResponse"
                  - $ref: "#/components/schemas/PaymentModificationFailedResponse"
              examples:
                refunded:
                  summary: Refund succeeded
                  value:
                    outcome: success
                    destination:
                      CARD: "10.50"
                    transaction_methods:
                      ECOM: "24.50"
                preAuthRefund:
                  summary: Refund of an uncaptured pre-auth
                  value:
                    outcome: success
                    message: "Pre-auth transaction: will be captured and then refunded"
                    destination:
                      CARD: "10.50"
                    transaction_methods:
                      ECOM: "24.50"
                refundTooHigh:
                  summary: Refund amount too high
                  value:
                    outcome: failed
                    message: Refund amount (30.00) cannot be greater than the original transaction
                      amount (24.50).
                alreadyRefunded:
                  summary: Already refunded
                  value:
                    outcome: failed
                    message: "Transaction already refunded: Item out of stock"
                invalidToken:
                  summary: Missing or invalid api_token
                  value:
                    outcome: failed
                    message: Token is empty or Invalid token
  /api2.php?action=capture:
    servers:
      - url: https://sandbox-payments.datmanpay.com
        description: Sandbox
      - url: https://payments.datmanpay.com
        description: Production
    post:
      operationId: capturePayment
      summary: Capture a pre-authorised payment
      description: >-
        Captures a payment that was only authorised (a pre-auth). The amount can
        be equal to or less than the authorised amount. Identify the payment by
        its `xref` (`O<order_id>M<merchant_id>T<payment_id>`), which you receive
        in the payment status webhook.


        Validation errors are returned with HTTP 200 and `outcome: failed`. When
        the request reaches the payment provider, its HTTP status is returned:
        201 when accepted, or an error status. `outcome` is then `success` even
        if the provider returned an error.
      tags:
        - Payment modifications
      security:
        - ApiTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CaptureOrAdjustmentRequest"
            examples:
              capture:
                summary: Capture the full amount
                value:
                  xref: O100247M663412T4821940
                  merchant_id: "663412"
                  amount: 24.5
      responses:
        "200":
          description: The request failed before reaching the payment provider.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentModificationFailedResponse"
              examples:
                captureTooHigh:
                  summary: Capture amount too high
                  value:
                    outcome: failed
                    code: 400
                    message: Capture amount cannot be greater than the authorised amount of 24.50
                notFound:
                  summary: Payment not found
                  value:
                    outcome: failed
                    message: No record found for the given order_id
                invalidToken:
                  summary: Missing or invalid api_token
                  value:
                    outcome: failed
                    message: Token is empty or Invalid token
        "201":
          description: The payment provider accepted the capture.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentModificationAcceptedResponse"
              examples:
                captureReceived:
                  summary: Capture received
                  value:
                    outcome: success
                    payment_reference: QFQTPCQ8HXSKGK82
                    status: received
                    amount: 24.5
        "500":
          $ref: "#/components/responses/PaymentModificationProviderFailed"
  /api2.php?action=adjustment:
    servers:
      - url: https://sandbox-payments.datmanpay.com
        description: Sandbox
      - url: https://payments.datmanpay.com
        description: Production
    post:
      operationId: adjustPaymentAmount
      summary: Adjust the amount of a pre-authorised payment
      description: >-
        Changes the authorised amount of a pre-auth before it's captured, for
        example when the final order total differs. Identify the payment by its
        `xref` (`O<order_id>M<merchant_id>T<payment_id>`). Pass `split_fee` to
        change the splits; without it the existing splits are kept.


        Validation errors are returned with HTTP 200 and `outcome: failed`. When
        the request reaches the payment provider, its HTTP status is returned:
        201 when accepted, 422 when refused, or an error status. `outcome` is
        then `success` even if the provider returned an error.
      tags:
        - Payment modifications
      security:
        - ApiTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CaptureOrAdjustmentRequest"
            examples:
              adjustment:
                summary: Increase the authorised amount
                value:
                  xref: O100247M663412T4821940
                  merchant_id: "663412"
                  amount: 27.75
      responses:
        "200":
          description: The request failed before reaching the payment provider.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentModificationFailedResponse"
              examples:
                overLimit:
                  summary: Amount over the merchant's limit
                  value:
                    outcome: failed
                    code: 1006
                    message: Amount exceeds the limit
                splitTooHigh:
                  summary: Splits too high
                  value:
                    outcome: failed
                    code: 400
                    message: Total split cannot be greater than or equal to order value (30.00 /
                      27.75)
                notFound:
                  summary: Payment not found
                  value:
                    outcome: failed
                    message: No record found for the given order_id
        "201":
          description: The payment provider accepted the adjustment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentModificationAcceptedResponse"
              examples:
                adjustmentAuthorised:
                  summary: Adjustment authorised
                  value:
                    outcome: success
                    payment_reference: QFQTPCQ8HXSKGK82
                    status: authorised
                    amount: 27.75
        "422":
          description: The payment provider refused the adjustment. `outcome` is still
            `success`; read `message` and `reason`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentModificationProviderError"
              examples:
                refused:
                  summary: Adjustment refused
                  value:
                    outcome: success
                    request_id: 5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                    message: Amount adjustment refused
                    resultCode: Refused
                    reason: Refused
        "500":
          $ref: "#/components/responses/PaymentModificationProviderFailed"
  /api2.php?action=auth_reversal:
    servers:
      - url: https://sandbox-payments.datmanpay.com
        description: Sandbox
      - url: https://payments.datmanpay.com
        description: Production
    post:
      operationId: reversePaymentAuthorisation
      summary: Reverse a pre-authorisation
      description: >-
        Cancels a payment that was authorised but not captured, releasing the
        hold on the shopper's funds. Identify the payment by its `xref`
        (`O<order_id>M<merchant_id>T<payment_id>`).


        Validation errors are returned with HTTP 200 and `outcome: failed`. When
        the request reaches the payment provider, its HTTP status is returned:
        201 when accepted, or an error status. `outcome` is then `success` even
        if the provider returned an error.
      tags:
        - Payment modifications
      security:
        - ApiTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthReversalRequest"
            examples:
              authReversal:
                summary: Reverse a pre-auth
                value:
                  xref: O100247M663412T4821940
                  merchant_id: "663412"
      responses:
        "200":
          description: The request failed before reaching the payment provider.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentModificationFailedResponse"
              examples:
                inProgress:
                  summary: Reversal already in progress
                  value:
                    outcome: failed
                    message: Auth reversal already in progress
                completed:
                  summary: Already reversed
                  value:
                    outcome: failed
                    message: Auth reversal already completed
        "201":
          description: The payment provider accepted the reversal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentModificationAcceptedResponse"
              examples:
                reversalReceived:
                  summary: Auth reversal received
                  value:
                    outcome: success
                    payment_reference: QFQTPCQ8HXSKGK82
                    status: received
        "500":
          $ref: "#/components/responses/PaymentModificationProviderFailed"
components:
  schemas:
    HostedSplitFee:
      title: HostedSplitFee
      type: object
      required:
        - partner_merchant_id
        - type_id
        - value
        - value_type
      properties:
        partner_merchant_id:
          type:
            - string
            - integer
          description: The `merchant_id` that receives this part of the payment.
          example: "63155481"
        type_id:
          type:
            - string
            - integer
          description: "Commission type: 1 Food/Goods, 2 Marketplace Fee, 3 Delivery Fee,
            4 Delivery Tip, 5 Restaurant Tip, 6 Service Charge."
          example: "3"
        value:
          type:
            - string
            - number
          description: The amount, or the percentage when `value_type` is `percentage`.
          example: "10.50"
        value_type:
          type: string
          enum:
            - amount
            - percentage
          example: amount
    RefundRequest:
      title: Refund (action=refund)
      type: object
      required:
        - merchant_id
        - order_id
        - amount
      properties:
        merchant_id:
          type:
            - string
            - integer
          description: The merchant that took the payment.
        order_id:
          type:
            - string
            - integer
          description: Your own order reference for the payment, as you sent it when paying.
        amount:
          type: number
          minimum: 0.01
          description: The amount to refund, in major units (e.g. 10.50).
        reason:
          type: string
          description: Why the payment is refunded.
        requested_by:
          type: string
          description: Who asked for the refund, for your records.
        refund_split_fee:
          $ref: "#/components/schemas/RefundSplitFee"
    RefundSplitFee:
      type: array
      description: How much to take back from each merchant that received part of the
        payment.
      items:
        type: object
        required:
          - partner_merchant_id
          - refund_amount
        properties:
          partner_merchant_id:
            type: integer
          refund_amount:
            type: number
            minimum: 0.01
    CaptureOrAdjustmentRequest:
      title: Capture or adjustment (action=capture, action=adjustment)
      type: object
      required:
        - xref
        - merchant_id
        - amount
      properties:
        xref:
          type: string
          pattern: ^O([A-Z]*\d+)M(\d+)T(\d+)$
          description: The payment's reference, `O<order_id>M<merchant_id>T<payment_id>`.
        merchant_id:
          type: string
          description: The merchant that took the payment, as a string.
        amount:
          type: number
          minimum: 0.01
          description: The amount to capture, or the new authorised amount for an
            adjustment, in major units.
        split_fee:
          type:
            - array
            - "null"
          description: Adjustment only. New split fees; when omitted the existing splits
            are kept.
          items:
            $ref: "#/components/schemas/HostedSplitFee"
    AuthReversalRequest:
      title: Auth reversal (action=auth_reversal)
      type: object
      required:
        - xref
        - merchant_id
      properties:
        xref:
          type: string
          pattern: ^O([A-Z]*\d+)M(\d+)T(\d+)$
          description: The payment's reference, `O<order_id>M<merchant_id>T<payment_id>`.
        merchant_id:
          type: string
          description: The merchant that took the payment, as a string.
    RefundResponse:
      type: object
      required:
        - outcome
      properties:
        outcome:
          type: string
          const: success
        message:
          type: string
          description: Present for an uncaptured pre-auth, which is captured first and
            then refunded.
        destination:
          type: object
          description: The amount refunded to each destination, as strings.
          additionalProperties:
            type: string
        transaction_methods:
          type: object
          description: The payment method of the original payment (ECOM, GPAY, APPLEPAY or
            WALLET) and its original total, as strings.
          additionalProperties:
            type: string
    PaymentModificationFailedResponse:
      type: object
      required:
        - outcome
      properties:
        outcome:
          type: string
          const: failed
        message:
          type: string
        code:
          type: integer
          description: An error code, present for some failures.
    PaymentModificationAcceptedResponse:
      type: object
      required:
        - outcome
        - payment_reference
        - status
      properties:
        outcome:
          type: string
          const: success
        payment_reference:
          type: string
          description: The payment provider's reference for the change.
        status:
          type: string
          description: The provider's status, e.g. `received` or `authorised`.
        amount:
          type: number
    PaymentModificationProviderError:
      type: object
      properties:
        outcome:
          type: string
          const: success
          description: Always `success` here; the HTTP status shows the failure.
        request_id:
          type: string
        message:
          type: string
        resultCode:
          type: string
        reason:
          type: string
  responses:
    PaymentModificationProviderFailed:
      description: The payment provider returned an error. `outcome` is still
        `success`; read `message`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentModificationProviderError"
          examples:
            providerError:
              summary: Provider error
              value:
                outcome: success
                request_id: 5b0d6f0e-4c1a-4b8e-9a51-3f3a2d1c7e90
                message: Unable to process your request at the moment. Please try again later.
  securitySchemes:
    ApiTokenAuth:
      type: apiKey
      in: header
      name: api_token
      description: API token issued by Datman.