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	String!	AccruPay session ID
token	String!	Short-lived token passed to the frontend/React SDK
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
transactionId	String	ID of the resulting transaction once verified
merchantTransactionProviderId	String	ID of the merchant-provider configuration used
createdAt	DateTimeISO!	When the session was created
updatedAt	DateTimeISO!	When the session was last updated
expiresAt	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
  $status: CLIENT_TRANSACTION_SESSION_STATUS
  $merchantInternalTransactionCode: String
) {
  merchantApiClientTransactionSessions(
    take: $take
    skip: $skip
    after: $after
    first: $first
    status: $status
    merchantInternalTransactionCode: $merchantInternalTransactionCode
  ) {
    edges {
      node {
        id
        token
        status
        kind
        merchantInternalTransactionCode
        createdAt
        expiresAt
      }
      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
status	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
    transactionId
    merchantTransactionProviderId
    createdAt
    updatedAt
    expiresAt
  }
}

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. Call this from your backend after starting a session and pass the result to your frontend.

Query

query GetSessionBaseConfig($id: String, $merchantInternalTransactionCode: String) {
  merchantApiClientTransactionSessionBaseConfig(
    id: $id
    merchantInternalTransactionCode: $merchantInternalTransactionCode
  ) {
    id
    providerData
  }
}

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

---

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
    expiresAt
  }
}

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",
      "billingAddress": "123 Main St",
      "billingCity": "New York",
      "billingState": "NY",
      "billingZip": "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 expiresAt } }",
    "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	No	Whether to store the payment method for future use
customerPaymentMethodId	String	No	Charge an existing stored payment method
billing.billingFirstName	String	No	Billing first name
billing.billingLastName	String	No	Billing last name
billing.billingEmail	String	No	Billing email
billing.billingPhone	String	No	Billing phone number
billing.billingAddress	String	No	Billing street address
billing.billingCity	String	No	Billing city
billing.billingState	String	No	Billing state or region
billing.billingZip	String	No	Billing postal code
billing.billingAddressCountry	COUNTRY_ISO_2	No	Billing country

---

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
    paymentMethod
    providerCode
    errorCode
    errorMessage
    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
    expiresAt
  }
}

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	No	Billing first name
billing.billingLastName	String	No	Billing last name
billing.billingEmail	String	No	Billing email
billing.billingAddressCountry	COUNTRY_ISO_2	No	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
  ) {
    id
    token
    providerCode
    status
    merchantInternalTransactionCode
    expiresAt
  }
}

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
  ) {
    id
    status
    action
    amount
    currency
    providerCode
    createdAt
    updatedAt
  }
}

Returns a Transaction with action: AUTHORIZATION. Capture the authorized amount with a separate settle/capture operation.

warning

Authorization sessions return a Transaction on verify, not a session. Check status to confirm the authorization was successful 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 token

query GetPublicSession($merchantPublicId: String!, $token: String!) {
  clientPublicTransactionSession(
    merchantPublicId: $merchantPublicId
    token: $token
  ) {
    id
    token
    status
    kind
    expiresAt
  }
}

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

clientPublicTransactionSessionBaseConfig — get provider config

Returns the provider-specific configuration needed to initialize the payment UI. The React SDK calls this automatically.

query GetPublicSessionBaseConfig($merchantPublicId: String!, $token: String!) {
  clientPublicTransactionSessionBaseConfig(
    merchantPublicId: $merchantPublicId
    token: $token
  ) {
    id
    providerData
  }
}

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.