Transactions

Transactions are the core payment record in AccruPay. Every charge, refund, void, authorization, and payout is represented as a transaction.

All operations on this page require the accrupay-api-secret header and must be called from your backend.

Transaction fields

The following fields are available on the MerchantTransaction type. Request only the fields you need.

Field	Type	Description
`id`	`ID!`	AccruPay transaction ID
`merchantInternalTransactionCode`	`String`	Your own reference code for this transaction
`providerCode`	`String!`	Provider-assigned transaction reference
`transactionProviderId`	`String!`	ID of the merchant-provider configuration used
`action`	`TRANSACTION_ACTION!`	Type of transaction (`PAYMENT`, `REFUND`, `VOID`, `AUTHORIZATION`, `SETTLE`, etc.)
`status`	`TRANSACTION_STATUS!`	Current status
`providerStatus`	`TRANSACTION_STATUS!`	Provider-derived status
`amount`	`BigInt!`	Transaction amount in minor currency units
`refundedAmount`	`BigInt`	Total amount refunded so far
`currency`	`CURRENCY!`	ISO 4217 currency code
`paymentMethodType`	`PAYMENT_METHOD`	Payment method type (`CARD`, `ACH`, `OTHER`)
`paymentMethodId`	`String`	ID of the stored payment method used, if any
`customerId`	`String`	AccruPay customer ID
`merchantInternalCustomerCode`	`String`	Your own reference code for the customer
`providerAuthorizationCode`	`String`	Authorization code from the provider (cards)
`providerError`	`String`	Provider error detail when the transaction fails
`transactionError`	`String`	AccruPay-level error detail, if any
`billingFirstName`	`String`	Billing first name
`billingLastName`	`String`	Billing last name
`billingEmail`	`String`	Billing email address
`billingPhone`	`String`	Billing phone number
`billingAddressLine1`	`String`	Billing street address line 1
`billingAddressLine2`	`String`	Billing street address line 2
`billingAddressCity`	`String`	Billing city
`billingAddressState`	`String`	Billing state or region
`billingAddressPostalCode`	`String`	Billing postal code
`billingAddressCountry`	`COUNTRY_ISO_2`	Billing country
`transactionDate`	`DateTimeISO!`	Effective date of the transaction
`createdAt`	`DateTimeISO!`	When the transaction was created
`updatedAt`	`DateTimeISO!`	When the transaction was last updated

The table above covers the commonly-used fields. The full MerchantTransaction type also exposes the following.

Lifecycle timestamps (all DateTimeISO, nullable unless noted):

Field	Description
`startedAt`	When processing began
`succeededAt`	When the transaction succeeded
`failedAt`	When it failed (declines are reflected in `status` + `failedAt`)
`canceledAt`	When canceled
`voidedAt`	When an authorization was voided
`refundedAt`	When the first refund was issued
`disputedAt`	When a dispute/chargeback opened
`providerLastSyncedAt`	Last provider sync
`providerLastVerifiedAt`	Last provider verification (`DateTimeISO!`, non-null)
`tokenExpiresAt`	Deprecated — use the Payment Session API

Relational fields:

Field	Type	Description
`paymentMethod`	`MerchantCustomerPaymentMethod`	The stored method used
`paymentMethodCode`	`String`	Provider payment-method code
`paymentPlan` / `paymentPlanId`	`MerchantPaymentPlan` / `String`	Associated plan, if any
`relatedTransaction` / `relatedTransactionId`	`MerchantTransaction` / `String`	Parent/related transaction (e.g. the auth a settle belongs to)
`transactionsRelated`	`[MerchantTransaction!]`	All related transactions
`clientTransactionSession` / `clientTransactionSessionId`	`MerchantClientTransactionSession` / `String`	Originating session
`transactionProvider`	`MerchantTransactionProvider!`	The provider connection that processed it

Provider & misc:

Field	Type	Description
`providerCustomerCode`	`String`	Provider's customer code
`providerRelatedCode`	`String`	Provider's related-transaction code
`storePaymentMethod`	`Boolean`	Whether the method was stored on this transaction
`payload`	`JSON!`	Raw provider payload
`code`	`String!`	Deprecated — use the other identifiers
`token`	`String`	Deprecated — use the Payment Session API

shipping*, user*, and device* blocks — the transaction echoes back the optional shipping, user, and device data submitted on the originating request. Field names mirror the input objects documented in Optional input objects (e.g. shippingFirstName, userEmail, deviceType).

For status semantics and transitions, see the TRANSACTION_STATUS state machine.

merchantApiTransactions — list transactions

Returns a paginated list of transactions for your merchant account.

Query

query ListTransactions(
  $take: Int
  $skip: Int
  $after: String
  $first: Int
  $status: TRANSACTION_STATUS
  $action: TRANSACTION_ACTION
  $currency: CURRENCY
  $merchantInternalTransactionCode: String
  $merchantInternalCustomerCode: String
  $customerId: String
  $paymentMethodId: String
  $transactionProviderId: String
  $transactionDateFrom: DateTimeISO
  $transactionDateTo: DateTimeISO
) {
  merchantApiTransactions(
    take: $take
    skip: $skip
    after: $after
    first: $first
    status: $status
    action: $action
    currency: $currency
    merchantInternalTransactionCode: $merchantInternalTransactionCode
    merchantInternalCustomerCode: $merchantInternalCustomerCode
    customerId: $customerId
    paymentMethodId: $paymentMethodId
    transactionProviderId: $transactionProviderId
    transactionDateFrom: $transactionDateFrom
    transactionDateTo: $transactionDateTo
  ) {
    edges {
      node {
        id
        merchantInternalTransactionCode
        providerCode
        action
        status
        amount
        currency
        paymentMethodType
        createdAt
        updatedAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

curl example

curl -X POST https://api.pay.accru.co/graphql \
  -H "Content-Type: application/json" \
  -H "accrupay-api-secret: YOUR_SECRET" \
  -d '{
    "query": "query ListTransactions($take: Int, $skip: Int, $status: TRANSACTION_STATUS) { merchantApiTransactions(take: $take, skip: $skip, status: $status) { edges { node { id merchantInternalTransactionCode status amount currency createdAt } } totalCount } }",
    "variables": { "take": 10, "skip": 0, "status": "SUCCEEDED" }
  }'

Filter parameters

Parameter	Type	Description
`take`	`Int`	Page size for offset pagination
`skip`	`Int`	Offset for offset pagination
`first`	`Int`	Page size for cursor pagination (forward)
`last`	`Int`	Page size for cursor pagination (backward)
`after`	`String`	Cursor for forward pagination
`before`	`String`	Cursor for backward pagination
`status`	`TRANSACTION_STATUS`	Filter by transaction status
`action`	`TRANSACTION_ACTION`	Filter by transaction action type
`currency`	`CURRENCY`	Filter by currency
`merchantInternalTransactionCode`	`String`	Filter by your transaction reference
`merchantInternalCustomerCode`	`String`	Filter by your customer reference
`customerId`	`String`	Filter by AccruPay customer ID
`paymentMethodId`	`String`	Filter by stored payment method ID
`transactionProviderId`	`String`	Filter by merchant-provider configuration ID
`transactionDateFrom`	`DateTimeISO`	Filter transactions dated on or after this timestamp
`transactionDateTo`	`DateTimeISO`	Filter transactions dated on or before this timestamp

merchantApiTransaction — get one transaction

Fetch a single transaction by any of three identifiers. Provide exactly one.

Query

query GetTransaction(
  $id: String
  $merchantInternalTransactionCode: String
  $providerCode: String
) {
  merchantApiTransaction(
    id: $id
    merchantInternalTransactionCode: $merchantInternalTransactionCode
    providerCode: $providerCode
  ) {
    id
    merchantInternalTransactionCode
    providerCode
    action
    status
    amount
    currency
    paymentMethodType
    providerError
    transactionError
    billingFirstName
    billingLastName
    billingEmail
    createdAt
    updatedAt
  }
}

Identifiers

Parameter	Type	Description
`id`	`String`	AccruPay transaction ID
`merchantInternalTransactionCode`	`String`	Your own transaction reference code
`providerCode`	`String`	Provider-assigned transaction reference

tip

Use merchantInternalTransactionCode when you need to look up a transaction using your own internal order or invoice ID.

merchantApiTransactionVoid — void a transaction

Voids an authorized or pending transaction before it is captured. Returns the updated transaction.

Mutation

mutation VoidTransaction(
  $id: String
  $merchantInternalTransactionCode: String
  $providerCode: String
) {
  merchantApiTransactionVoid(
    id: $id
    merchantInternalTransactionCode: $merchantInternalTransactionCode
    providerCode: $providerCode
  ) {
    id
    status
    action
    amount
    currency
    updatedAt
  }
}

Identifiers

Parameter	Type	Description
`id`	`String`	AccruPay transaction ID
`merchantInternalTransactionCode`	`String`	Your own transaction reference code
`providerCode`	`String`	Provider-assigned transaction reference

Provide exactly one identifier.

merchantApiTransactionRefund — refund a transaction

Refunds a previously completed transaction. You must always provide the amount to refund.

Mutation

mutation RefundTransaction(
  $amount: BigInt!
  $id: String
  $merchantInternalTransactionCode: String
  $providerCode: String
) {
  merchantApiTransactionRefund(
    amount: $amount
    id: $id
    merchantInternalTransactionCode: $merchantInternalTransactionCode
    providerCode: $providerCode
  ) {
    id
    status
    action
    amount
    currency
    updatedAt
  }
}

curl example

curl -X POST https://api.pay.accru.co/graphql \
  -H "Content-Type: application/json" \
  -H "accrupay-api-secret: YOUR_SECRET" \
  -d '{
    "query": "mutation RefundTransaction($amount: BigInt!, $id: String) { merchantApiTransactionRefund(amount: $amount, id: $id) { id status action amount currency updatedAt } }",
    "variables": { "amount": 5000, "id": "txn_abc123" }
  }'

Parameters

Parameter	Type	Required	Description
`amount`	`BigInt!`	Yes	Amount to refund in minor currency units
`id`	`String`	One required	AccruPay transaction ID
`merchantInternalTransactionCode`	`String`	One required	Your own transaction reference code
`providerCode`	`String`	One required	Provider-assigned transaction reference

warning

amount is always required. There is no full-refund shorthand — you must explicitly pass the full transaction amount if you intend to refund completely. Partial refunds use the same mutation with a smaller amount.

merchantApiTransactionSyncOne — sync transaction state

Fetches the latest state of a transaction from the provider and updates AccruPay's record. Use this when you suspect the local status is stale or after a webhook is delayed.

Mutation

mutation SyncTransaction(
  $merchantTransactionProviderId: String!
  $id: String
  $merchantInternalTransactionCode: String
  $providerCode: String
) {
  merchantApiTransactionSyncOne(
    merchantTransactionProviderId: $merchantTransactionProviderId
    id: $id
    merchantInternalTransactionCode: $merchantInternalTransactionCode
    providerCode: $providerCode
  ) {
    id
    status
    action
    amount
    currency
    updatedAt
  }
}

Parameters

Parameter	Type	Required	Description
`merchantTransactionProviderId`	`String!`	Yes	ID of the merchant-provider configuration to sync against
`id`	`String`	One required	AccruPay transaction ID
`merchantInternalTransactionCode`	`String`	One required	Your own transaction reference code
`providerCode`	`String`	One required	Provider-assigned transaction reference

note

merchantTransactionProviderId is always required for sync, in addition to one transaction identifier. This tells AccruPay which provider connection to query for the latest state.

Transaction fields​

merchantApiTransactions — list transactions​

Query​

curl example​

Filter parameters​

merchantApiTransaction — get one transaction​

Query​

Identifiers​

merchantApiTransactionVoid — void a transaction​

Mutation​

Identifiers​

merchantApiTransactionRefund — refund a transaction​

Mutation​

curl example​

Parameters​

merchantApiTransactionSyncOne — sync transaction state​

Mutation​

Parameters​

Transaction fields

merchantApiTransactions — list transactions

Query

curl example

Filter parameters

merchantApiTransaction — get one transaction

Query

Identifiers

merchantApiTransactionVoid — void a transaction

Mutation

Identifiers

merchantApiTransactionRefund — refund a transaction

Mutation

curl example

Parameters

merchantApiTransactionSyncOne — sync transaction state

Mutation

Parameters