Sessions

Client transaction sessions drive the payment UI flow. Your backend creates a session, passes its token to the frontend, and the customer completes the payment or adds a payment method using the provider's hosted UI. Once the customer is done, your backend verifies the session to get the final result.

AccruPay supports three session flows:

Payment session — charge a payment method
Add-payment-method session — store a payment method without charging
Authorization session — authorize (reserve) funds without capturing

Session fields

The following fields are returned by session queries and mutations.

Field	Type	Description
`id`	`ID!`	AccruPay session ID
`token`	`String`	Short-lived token passed to the frontend/React SDK (nullable)
`providerCode`	`String!`	Provider-assigned session reference
`status`	`CLIENT_TRANSACTION_SESSION_STATUS!`	Current session status
`kind`	`CLIENT_TRANSACTION_SESSION_KIND!`	Whether the session was started from CLIENT or SERVER context
`merchantInternalTransactionCode`	`String`	Your own reference code for this session
`transactions`	`[MerchantTransaction!]`	Resulting transaction(s), available after verify
`transactionProviderId`	`String!`	ID of the merchant-provider configuration used
`createdAt`	`DateTimeISO!`	When the session was created
`updatedAt`	`DateTimeISO!`	When the session was last updated
`tokenExpiresAt`	`DateTimeISO`	When the session will expire

merchantApiClientTransactionSessions — list sessions

Returns a paginated list of client transaction sessions.

Query

query ListSessions(
  $take: Int
  $skip: Int
  $after: String
  $first: Int
  $providerStatus: CLIENT_TRANSACTION_SESSION_STATUS
  $merchantInternalTransactionCode: String
) {
  merchantApiClientTransactionSessions(
    take: $take
    skip: $skip
    after: $after
    first: $first
    providerStatus: $providerStatus
    merchantInternalTransactionCode: $merchantInternalTransactionCode
  ) {
    edges {
      node {
        id
        token
        status
        kind
        merchantInternalTransactionCode
        createdAt
        tokenExpiresAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

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)
`after`	`String`	Cursor for forward pagination
`providerStatus`	`CLIENT_TRANSACTION_SESSION_STATUS`	Filter by session status
`merchantInternalTransactionCode`	`String`	Filter by your transaction reference

merchantApiClientTransactionSession — get one session

Fetch a single session by ID or by your internal transaction code.

Query

query GetSession(
  $id: String
  $merchantInternalTransactionCode: String
) {
  merchantApiClientTransactionSession(
    id: $id
    merchantInternalTransactionCode: $merchantInternalTransactionCode
  ) {
    id
    token
    providerCode
    status
    kind
    merchantInternalTransactionCode
    transactionProviderId
    createdAt
    updatedAt
    tokenExpiresAt
    transactions {
      id
      status
    }
  }
}

Identifiers

Parameter	Type	Description
`id`	`String`	AccruPay session ID
`merchantInternalTransactionCode`	`String`	Your own transaction reference code

merchantApiClientTransactionSessionBaseConfig — fetch provider config

Returns the provider configuration needed to initialize a payment session on the frontend. Selected by provider (not by session). Return type MerchantClientTransactionSessionBaseConfig exposes provider and data (a provider-specific union).

Query

query GetSessionBaseConfig(
  $merchantTransactionProviderId: String
  $transactionProvider: TRANSACTION_PROVIDER
) {
  merchantApiClientTransactionSessionBaseConfig(
    merchantTransactionProviderId: $merchantTransactionProviderId
    transactionProvider: $transactionProvider
  ) {
    provider
    data {
      ... on MerchantClientTransactionSessionNuveiBaseConfig {
        env
        merchantId
        merchantSiteId
      }
      ... on MerchantClientTransactionSessionGenericBaseConfig {
        publicKey
      }
    }
  }
}

Parameter	Type	Description
`merchantTransactionProviderId`	`String`	Target a specific configured provider by its internal ID
`transactionProvider`	`TRANSACTION_PROVIDER`	Alternatively, select the provider by enum

Payment session mutations

merchantApiClientTransactionPaymentSessionStartV2 — start a payment session

Creates a new client payment session. Returns a session with a token to pass to the frontend.

Mutation

mutation StartPaymentSession(
  $transactionProvider: TRANSACTION_PROVIDER!
  $data: MerchantApiClientTransactionPaymentSessionStartSchema!
) {
  merchantApiClientTransactionPaymentSessionStartV2(
    transactionProvider: $transactionProvider
    data: $data
  ) {
    id
    token
    providerCode
    status
    merchantInternalTransactionCode
    tokenExpiresAt
  }
}

Variables

{
  "transactionProvider": "YOUR_PROVIDER",
  "data": {
    "amount": 10000,
    "currency": "USD",
    "merchantInternalTransactionCode": "order-001",
    "merchantInternalCustomerCode": "customer-456",
    "storePaymentMethod": false,
    "billing": {
      "billingFirstName": "Jane",
      "billingLastName": "Smith",
      "billingEmail": "jane@example.com",
      "billingPhone": "+15555550100",
      "billingAddressLine1": "123 Main St",
      "billingAddressCity": "New York",
      "billingAddressState": "NY",
      "billingAddressPostalCode": "10001",
      "billingAddressCountry": "US"
    }
  }
}

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 StartPaymentSession($transactionProvider: TRANSACTION_PROVIDER!, $data: MerchantApiClientTransactionPaymentSessionStartSchema!) { merchantApiClientTransactionPaymentSessionStartV2(transactionProvider: $transactionProvider, data: $data) { id token providerCode status tokenExpiresAt } }",
    "variables": {
      "transactionProvider": "YOUR_PROVIDER",
      "data": {
        "amount": 10000,
        "currency": "USD",
        "merchantInternalTransactionCode": "order-001",
        "merchantInternalCustomerCode": "customer-456",
        "storePaymentMethod": false,
        "billing": {
          "billingFirstName": "Jane",
          "billingLastName": "Smith",
          "billingEmail": "jane@example.com",
          "billingAddressCountry": "US"
        }
      }
    }
  }'

Input schema

Field	Type	Required	Description
`amount`	`BigInt!`	Yes	Payment amount in minor currency units
`currency`	`CURRENCY!`	Yes	ISO 4217 currency code
`merchantInternalTransactionCode`	`String!`	Yes	Your unique reference for this transaction
`merchantInternalCustomerCode`	`String`	No	Your reference for the customer
`storePaymentMethod`	`Boolean!`	Yes	Whether to store the payment method for future use
`customer`	`MerchantCustomerSelector`	No	Customer selector. When provided, `merchantInternalCustomerCode` is required within it.
`billing.billingFirstName`	`String`	Yes	Billing first name
`billing.billingLastName`	`String`	Yes	Billing last name
`billing.billingEmail`	`String`	Yes	Billing email
`billing.billingAddressCountry`	`COUNTRY_ISO_2`	Yes	Billing country
`billing.billingPhone`	`String`	No	Billing phone number
`billing.billingAddressLine1`	`String`	No	Billing street address line 1
`billing.billingAddressLine2`	`String`	No	Billing street address line 2
`billing.billingAddressCity`	`String`	No	Billing city
`billing.billingAddressState`	`String`	No	Billing state or region
`billing.billingAddressPostalCode`	`String`	No	Billing postal code

The session-start input also accepts optional shipping, device, and user objects — see Optional input objects.

merchantApiClientTransactionPaymentSessionVerify — verify a payment session

Verifies a completed payment session and returns the resulting transaction. Call this from your backend after the customer completes the payment UI.

Mutation

mutation VerifyPaymentSession(
  $id: String
  $token: String
  $providerCode: String
  $merchantInternalTransactionCode: String
) {
  merchantApiClientTransactionPaymentSessionVerify(
    id: $id
    token: $token
    providerCode: $providerCode
    merchantInternalTransactionCode: $merchantInternalTransactionCode
  ) {
    id
    status
    action
    amount
    currency
    paymentMethodType
    providerCode
    providerError
    transactionError
    createdAt
    updatedAt
  }
}

Identifiers

Parameter	Type	Description
`id`	`String`	AccruPay session ID
`token`	`String`	Session token (from the start mutation response)
`providerCode`	`String`	Provider-assigned session reference
`merchantInternalTransactionCode`	`String`	Your own transaction reference code

warning

merchantApiClientTransactionPaymentSessionVerify returns a Transaction, not a session. After calling this mutation, check the transaction's status field to determine whether the payment succeeded.

Add-payment-method session mutations

Use these to store a payment method without charging it.

merchantApiClientTransactionAddPaymentMethodSessionStart

mutation StartAddPaymentMethodSession(
  $transactionProvider: TRANSACTION_PROVIDER!
  $data: MerchantApiClientTransactionAddPaymentMethodSessionStartSchema!
) {
  merchantApiClientTransactionAddPaymentMethodSessionStart(
    transactionProvider: $transactionProvider
    data: $data
  ) {
    id
    token
    providerCode
    status
    merchantInternalTransactionCode
    tokenExpiresAt
  }
}

Input schema

Field	Type	Required	Description
`currency`	`CURRENCY!`	Yes	Currency for the session
`merchantInternalTransactionCode`	`String!`	Yes	Your unique reference for this operation
`merchantInternalCustomerCode`	`String`	No	Your reference for the customer
`billing.billingFirstName`	`String`	Yes	Billing first name
`billing.billingLastName`	`String`	Yes	Billing last name
`billing.billingEmail`	`String`	Yes	Billing email
`billing.billingAddressCountry`	`COUNTRY_ISO_2`	Yes	Billing country

merchantApiClientTransactionAddPaymentMethodSessionVerify

mutation VerifyAddPaymentMethodSession(
  $id: String
  $token: String
  $providerCode: String
  $merchantInternalTransactionCode: String
) {
  merchantApiClientTransactionAddPaymentMethodSessionVerify(
    id: $id
    token: $token
    providerCode: $providerCode
    merchantInternalTransactionCode: $merchantInternalTransactionCode
  ) {
    id
    status
    action
    providerCode
    createdAt
    updatedAt
  }
}

Identifiers are the same four as the payment session verify mutation. Returns a Transaction with action: ADD_PAYMENT_METHOD.

warning

As with payment session verify, this returns a Transaction — not a payment method object. To retrieve the stored payment method, query merchantApiCustomerPaymentMethods filtered by merchantInternalCustomerCode after a successful verify.

Authorization session mutations

Use these to authorize (reserve) funds without capturing them immediately.

merchantApiClientTransactionAuthorizationSessionStart

mutation StartAuthorizationSession(
  $transactionProvider: TRANSACTION_PROVIDER!
  $data: MerchantApiClientTransactionAuthorizationSessionStartSchema!
) {
  merchantApiClientTransactionAuthorizationSessionStart(
    transactionProvider: $transactionProvider
    data: $data
  ) {
    session {
      id
      token
      providerCode
      status
      merchantInternalTransactionCode
      tokenExpiresAt
    }
  }
}

Returns a MerchantClientTransactionSessionContext — the session (with its token) is under session. The input schema is the same as the payment session start schema; amount and currency are required.

merchantApiClientTransactionAuthorizationSessionVerify

mutation VerifyAuthorizationSession(
  $id: String
  $token: String
  $providerCode: String
  $merchantInternalTransactionCode: String
) {
  merchantApiClientTransactionAuthorizationSessionVerify(
    id: $id
    token: $token
    providerCode: $providerCode
    merchantInternalTransactionCode: $merchantInternalTransactionCode
  ) {
    session {
      id
      status
    }
    transactions {
      id
      action
      status
      amount
      currency
      providerCode
    }
  }
}

Returns a MerchantClientTransactionSessionContext. The authorization transaction(s) are under transactions (each with action: AUTHORIZATION). Capture the authorized amount with a separate settle operation.

warning

Authorization session verify returns a MerchantClientTransactionSessionContext, not a flat transaction. The authorization transaction(s) are under transactions (each with action: AUTHORIZATION) — check their status before proceeding to capture.

Client Public API

These operations do not require the accrupay-api-secret header. They are used by the React SDK and frontend code to read session data without exposing your secret.

clientPublicTransactionSession — get session by ID

Returns MerchantClientPublicTransactionSessionData: the resolved provider, the transactionSession, and the provider baseConfig.

query GetPublicSession($merchantPublicId: String!, $transactionSessionId: String!) {
  clientPublicTransactionSession(
    merchantPublicId: $merchantPublicId
    transactionSessionId: $transactionSessionId
  ) {
    provider
    transactionSession {
      id
      status
      kind
      token
      tokenExpiresAt
    }
  }
}

Parameter	Type	Required	Description
`merchantPublicId`	`String!`	Yes	Your merchant public ID (safe for frontend use)
`transactionSessionId`	`String!`	Yes	Session ID from the start mutation

note

baseConfig on this type is MerchantClientTransactionSessionBaseConfigData, a provider-specific union (generic or Nuvei). Select it with inline fragments, or use the dedicated clientPublicTransactionSessionBaseConfig query below.

clientPublicTransactionSessionBaseConfig — get provider config

Returns the provider-specific configuration needed to initialize the payment UI. The React SDK calls this automatically. Return type MerchantClientTransactionSessionBaseConfig exposes provider and data (a provider-specific union).

query GetPublicSessionBaseConfig(
  $merchantPublicId: String!
  $transactionSessionId: String
  $transactionProvider: TRANSACTION_PROVIDER
) {
  clientPublicTransactionSessionBaseConfig(
    merchantPublicId: $merchantPublicId
    transactionSessionId: $transactionSessionId
    transactionProvider: $transactionProvider
  ) {
    provider
    data {
      # provider-specific union — select with inline fragments
      ... on MerchantClientTransactionSessionNuveiBaseConfig {
        env
        merchantId
        merchantSiteId
      }
      ... on MerchantClientTransactionSessionGenericBaseConfig {
        publicKey
      }
    }
  }
}

Parameter	Type	Required	Description
`merchantPublicId`	`String!`	Yes	Your merchant public ID (safe for frontend use)
`transactionSessionId`	`String`	No	Session ID from the start mutation
`transactionProvider`	`TRANSACTION_PROVIDER`	No	Target a specific provider's config

note

These Client Public API queries use merchantPublicId instead of the accrupay-api-secret header. The public ID is safe to embed in browser code. Never expose your API secret to the frontend.

Session fields​

merchantApiClientTransactionSessions — list sessions​

Query​

Filter parameters​

merchantApiClientTransactionSession — get one session​

Query​

Identifiers​

merchantApiClientTransactionSessionBaseConfig — fetch provider config​

Query​

Payment session mutations​

merchantApiClientTransactionPaymentSessionStartV2 — start a payment session​

Mutation​

Variables​

curl example​

Input schema​

merchantApiClientTransactionPaymentSessionVerify — verify a payment session​

Mutation​

Identifiers​

Add-payment-method session mutations​

merchantApiClientTransactionAddPaymentMethodSessionStart​

Input schema​

merchantApiClientTransactionAddPaymentMethodSessionVerify​

Authorization session mutations​

merchantApiClientTransactionAuthorizationSessionStart​

merchantApiClientTransactionAuthorizationSessionVerify​

Client Public API​

clientPublicTransactionSession — get session by ID​

clientPublicTransactionSessionBaseConfig — get provider config​

Session fields

merchantApiClientTransactionSessions — list sessions

Query

Filter parameters

merchantApiClientTransactionSession — get one session

Query

Identifiers

merchantApiClientTransactionSessionBaseConfig — fetch provider config

Query

Payment session mutations

merchantApiClientTransactionPaymentSessionStartV2 — start a payment session

Mutation

Variables

curl example

Input schema

merchantApiClientTransactionPaymentSessionVerify — verify a payment session

Mutation

Identifiers

Add-payment-method session mutations

merchantApiClientTransactionAddPaymentMethodSessionStart

Input schema

merchantApiClientTransactionAddPaymentMethodSessionVerify

Authorization session mutations

merchantApiClientTransactionAuthorizationSessionStart

merchantApiClientTransactionAuthorizationSessionVerify

Client Public API

clientPublicTransactionSession — get session by ID

clientPublicTransactionSessionBaseConfig — get provider config