Create, update and refund external transactions

note

merchantCode and transactionId in these examples are placeholders — use a real merchant from your context and ids from paymentExternalTransactions.

Use the paymentExternalTransactionCreate, paymentExternalTransactionUpdate and paymentExternalTransactionRefund mutations to record the payment activity of an external gateway in OMS.

Create an external transaction

Use paymentExternalTransactionCreate mutation to add a new payment transaction to OMS. The mutation accepts a PaymentExternalTransactionCreateInput object — its reference lists all the available fields.

This mutation creates the provider-side payment record for a merchant. Use it when the payment gateway sends OMS the first event for a transaction, such as an authorized or completed payment.

Field notes:

• merchantCode identifies the payment merchant that owns the transaction; number is the transaction identifier assigned by the provider.
• referenceCode is the number of the order the transaction pays. It is not validated at creation (the order might not exist in OMS yet): OMS links the transaction to the order when it finds the two consistent, and from then on the transaction exposes it in order and the order lists it in saleTransactions. Until then order is null.
• amount is positive for a payment: a positive amount is matched to an order, a negative one to a return. status is pended for a transaction waiting capture, completed once captured, failed if it failed.
• fees records the provider fees: each fee requires amount and currency; description and exchangeRate are optional.

Request

mutation createExternalTransaction {
  paymentExternalTransactionCreate(
    input: {
      merchantCode: "1"
      number: "12345678"
      provider: "visa"
      amount: 10.1
      currency: "EUR"
      referenceCode: "12345"
      status: pended
      timestamp: "2026-04-03T10:15:30.000Z"
      fees: [
        {
          amount: 0.2
          currency: "EUR"
          description: "Interchange"
          exchangeRate: 1
        }
      ]
    }
  ) {
    id
  }
}

Open in playground

Response

{
  "data": {
    "paymentExternalTransactionCreate": {
      "id": "1005"
    }
  },
  "extensions": {
    "queryComplexity": 2,
    "bucketBalance": 9998,
    "bucketRestoreRate": 100
  }
}

Update an external transaction

Use paymentExternalTransactionUpdate mutation to update an existing payment transaction in OMS. The mutation accepts a PaymentExternalTransactionUpdateInput object — its reference lists all the available fields.

This mutation updates mutable transaction data after OMS has already stored the external transaction. It is typically used to move a transaction from pended to completed or failed, or to attach final provider fee data.

Field notes:

• status transitions are validated: an invalid one (including the status the transaction already has) is rejected with Invalid status update and the error code BAD_REQUEST. The allowed transitions are listed in Transaction statuses.
• timestamp goes with status: OMS stores it as startedAt, transactedAt or failedAt depending on the submitted status.
• fees does not replace the fee list: a fee with id updates that fee, a fee without id adds a new one.

Request

mutation updateExternalTransaction {
  paymentExternalTransactionUpdate(
    transactionId: "1005"
    input: {
      status: completed
      timestamp: "2026-04-22T17:15:30.000Z"
      fees: [
        {
          id: "112"
          amount: 0.66
          currency: "EUR"
          description: "Interchange"
          exchangeRate: 1
        }
      ]
    }
  ) {
    id
  }
}

Open in playground

Response

{
  "data": {
    "paymentExternalTransactionUpdate": {
      "id": "1005"
    }
  },
  "extensions": {
    "queryComplexity": 2,
    "bucketBalance": 9998,
    "bucketRestoreRate": 100
  }
}

Refund an external transaction

Use paymentExternalTransactionRefund mutation to create a refund for an existing transaction. The mutation accepts a PaymentExternalTransactionRefundInput object — its reference lists all the available fields.

The refund is a child transaction linked to the original payment, and the mutation returns the refund transaction, not the original one: keep its id if you need to update the refund later. How refunds and the original transaction interact is explained in Refund transactions.

Field notes:

• transactionId is the original transaction being refunded.
• referenceCode is the number of the repayment request (return) the refund belongs to, or the order's number: OMS resolves the association from either one, and a linked refund exposes the return in repaymentRequest. The refund is in any case linked to the original transaction (and, through it, to the order) via saleTransaction.
• amount is negative for a refund: a negative amount is matched to a return, never to an order. status, timestamp and fees work as at creation, on the refund transaction.
• A completed refund moves the original transaction to partially_refunded or totally_refunded; a pended refund does not affect it until it completes.

Request

mutation refundExternalTransaction {
  paymentExternalTransactionRefund(
    transactionId: "1005"
    input: {
      number: "R123456"
      provider: "visa"
      amount: -1.2
      currency: "EUR"
      referenceCode: "R123456"
      status: pended
      timestamp: "2026-04-03T10:15:30.000Z"
      fees: [
        {
          amount: 0.4
          currency: "EUR"
          description: "Interchange"
          exchangeRate: 1
        }
      ]
    }
  ) {
    id
  }
}

Open in playground

Response

{
  "data": {
    "paymentExternalTransactionRefund": {
      "id": "1006"
    }
  },
  "extensions": {
    "queryComplexity": 2,
    "bucketBalance": 9998,
    "bucketRestoreRate": 100
  }
}

Relevant permissions

The operations in this page require the following permissions on the API credentials — they are configured for you by Calicantus.

• payment_transaction:mutation:payment_external_transaction_create
• payment_transaction:mutation:payment_external_transaction_update
• payment_transaction:mutation:payment_external_transaction_refund
• payment_transaction:read