Skip to main content

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 Transaction type. Request only the fields you need.

FieldTypeDescription
idString!AccruPay transaction ID
merchantInternalTransactionCodeStringYour own reference code for this transaction
providerCodeStringProvider-assigned transaction reference
merchantTransactionProviderIdStringID of the merchant-provider configuration used
actionTRANSACTION_ACTION!Type of transaction (PAYMENT, REFUND, VOID, etc.)
statusTRANSACTION_STATUS!Current status
amountBigIntTransaction amount in minor currency units
currencyCURRENCYISO 4217 currency code
paymentMethodPAYMENT_METHODPayment method type (CARD, ACH, OTHER)
achSecCodeTRANSACTION_ACH_SECCODEACH SEC code (ACH transactions only)
errorCodeStringProvider error code if status is ERROR or FAILED
errorMessageStringHuman-readable error message
customerPaymentMethodIdStringID of the stored payment method used, if any
customerIdStringAccruPay customer ID
merchantInternalCustomerCodeStringYour own reference code for the customer
billingFirstNameStringBilling first name
billingLastNameStringBilling last name
billingEmailStringBilling email address
billingPhoneStringBilling phone number
billingAddressStringBilling street address
billingCityStringBilling city
billingStateStringBilling state or region
billingZipStringBilling postal code
billingAddressCountryCOUNTRY_ISO_2Billing country
createdAtDateTimeISO!When the transaction was created
updatedAtDateTimeISO!When the transaction was last updated

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
  $customerPaymentMethodId: String
  $merchantTransactionProviderId: String
  $createdAtFrom: DateTimeISO
  $createdAtTo: DateTimeISO
) {
  merchantApiTransactions(
    take: $take
    skip: $skip
    after: $after
    first: $first
    status: $status
    action: $action
    currency: $currency
    merchantInternalTransactionCode: $merchantInternalTransactionCode
    merchantInternalCustomerCode: $merchantInternalCustomerCode
    customerId: $customerId
    customerPaymentMethodId: $customerPaymentMethodId
    merchantTransactionProviderId: $merchantTransactionProviderId
    createdAtFrom: $createdAtFrom
    createdAtTo: $createdAtTo
  ) {
    edges {
      node {
        id
        merchantInternalTransactionCode
        providerCode
        action
        status
        amount
        currency
        paymentMethod
        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​

ParameterTypeDescription
takeIntPage size for offset pagination
skipIntOffset for offset pagination
firstIntPage size for cursor pagination (forward)
lastIntPage size for cursor pagination (backward)
afterStringCursor for forward pagination
beforeStringCursor for backward pagination
statusTRANSACTION_STATUSFilter by transaction status
actionTRANSACTION_ACTIONFilter by transaction action type
currencyCURRENCYFilter by currency
merchantInternalTransactionCodeStringFilter by your transaction reference
merchantInternalCustomerCodeStringFilter by your customer reference
customerIdStringFilter by AccruPay customer ID
customerPaymentMethodIdStringFilter by stored payment method ID
merchantTransactionProviderIdStringFilter by merchant-provider configuration ID
createdAtFromDateTimeISOFilter transactions created on or after this timestamp
createdAtToDateTimeISOFilter transactions created 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
    paymentMethod
    errorCode
    errorMessage
    billingFirstName
    billingLastName
    billingEmail
    createdAt
    updatedAt
  }
}

Identifiers​

ParameterTypeDescription
idStringAccruPay transaction ID
merchantInternalTransactionCodeStringYour own transaction reference code
providerCodeStringProvider-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​

ParameterTypeDescription
idStringAccruPay transaction ID
merchantInternalTransactionCodeStringYour own transaction reference code
providerCodeStringProvider-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​

ParameterTypeRequiredDescription
amountBigInt!YesAmount to refund in minor currency units
idStringOne requiredAccruPay transaction ID
merchantInternalTransactionCodeStringOne requiredYour own transaction reference code
providerCodeStringOne requiredProvider-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​

ParameterTypeRequiredDescription
merchantTransactionProviderIdString!YesID of the merchant-provider configuration to sync against
idStringOne requiredAccruPay transaction ID
merchantInternalTransactionCodeStringOne requiredYour own transaction reference code
providerCodeStringOne requiredProvider-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.