Server Payments

Server payment mutations charge a stored payment method or initiate an ACH payment directly from your backend, without a client-side checkout session. These operations require your API secret and must only be called from your server.

note

Every data input on this page also accepts optional shipping, device, and user objects alongside billing. See Optional input objects for their fields.

---

Charge a Stored Payment Method

merchantApiServerPaymentMethodTransactionCreate

Charge a previously stored payment method in a single server-side call.

mutation ChargeStoredMethod(
  $providerId: String
  $provider: TRANSACTION_PROVIDER
  $data: MerchantApiServerPaymentMethodTransactionCreateSchema!
) {
  merchantApiServerPaymentMethodTransactionCreate(
    merchantTransactionProviderId: $providerId
    transactionProvider: $provider
    data: $data
  ) {
    id
    status
    amount
    currency
    providerCode
    providerAuthorizationCode
    createdAt
  }
}

Top-level arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	One of the two	AccruPay provider record ID
transactionProvider	TRANSACTION_PROVIDER	One of the two	Provider enum (e.g. NUVEI). Use when you have one provider per type
data	MerchantApiServerPaymentMethodTransactionCreateSchema	Yes	Charge details

Provide exactly one of merchantTransactionProviderId or transactionProvider.

data fields

Field	Type	Required	Description
merchantCustomerPaymentMethodId	String	Yes	AccruPay stored payment method UUID
merchantInternalTransactionCode	String	Yes	Your idempotency key / order ID
amount	BigInt	Yes	Charge amount in smallest currency unit (e.g. cents)
currency	CURRENCY	Yes	Currency enum (e.g. USD)
billing	BillingDataSchema	Yes	Billing address details
merchantInternalCustomerCode	String	No	Deprecated. Pass customer via the payment method instead

BillingDataSchema fields

Field	Type	Required	Description
billingFirstName	String	Yes	Cardholder first name
billingLastName	String	Yes	Cardholder last name
billingEmail	String	Yes	Billing email address
billingAddressCountry	COUNTRY_ISO_2	Yes	Two-letter country code enum
billingAddressLine1	String	No	Street address
billingAddressLine2	String	No	Apartment, suite, etc.
billingAddressCity	String	No	City
billingAddressState	String	No	State or province
billingAddressPostalCode	String	No	Postal code
billingPhone	String	No	Phone number

Return shape

Field	Type	Description
id	String	AccruPay transaction UUID
status	TRANSACTION_STATUS	SUCCEEDED, PENDING, FAILED, DECLINED, ERROR
amount	BigInt	Charged amount
currency	CURRENCY	Currency
providerCode	String	Provider's transaction reference
providerAuthorizationCode	String	Authorization code from the card network
providerError	String	Raw provider decline reason when status is DECLINED or FAILED
createdAt	DateTimeISO	Transaction creation timestamp

warning

Check transaction.status in the response. A DECLINED or FAILED status is not a GraphQL error — the mutation resolves successfully with a non-approved status. See Errors for details.

---

ACH Payment

merchantApiServerAchPaymentTransactionCreate

Initiate an ACH bank-to-bank payment from your server. The customer's bank account details are passed directly in the mutation.

mutation CreateAchPayment(
  $providerId: String
  $provider: TRANSACTION_PROVIDER
  $data: MerchantApiServerAchPaymentTransactionCreateSchema!
) {
  merchantApiServerAchPaymentTransactionCreate(
    merchantTransactionProviderId: $providerId
    transactionProvider: $provider
    data: $data
  ) {
    id
    status
    amount
    currency
    providerCode
    createdAt
  }
}

Top-level arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	One of the two	AccruPay provider record ID
transactionProvider	TRANSACTION_PROVIDER	One of the two	Provider enum
data	MerchantApiServerAchPaymentTransactionCreateSchema	Yes	ACH payment details

data fields

Field	Type	Required	Description
merchantInternalTransactionCode	String	Yes	Your idempotency key / order ID
amount	BigInt	Yes	Payment amount in smallest currency unit
currency	CURRENCY	Yes	Currency enum (e.g. USD)
billing	BillingDataSchema	Yes	Billing details (same shape as above)
storePaymentMethod	Boolean	Yes	Whether to store the bank account for future use
ach.accountNumber	String	Yes	Bank account number
ach.routingNumber	String	Yes	ABA routing number
ach.secCode	TRANSACTION_ACH_SECCODE	No	ACH SEC code: WEB, CCD, TEL, or UNKNOWN
ach.entityType	ENTITY_TYPE	No	INDIVIDUAL or COMPANY
customer	MerchantCustomerSelector	No	Customer selector for this payment. When provided, merchantInternalCustomerCode is required within it.
merchantInternalCustomerCode	String	No	Legacy top-level customer code. Prefer the customer selector.

note

ACH transactions are not settled synchronously. The initial response will typically have a PENDING status. The provider sends a settlement or return notification asynchronously, and AccruPay updates the transaction state when that event is received. Use merchantApiTransactionSyncOne or poll merchantApiTransaction to check the final status.

---

Server Authorization Session

Use these mutations when you want to authorize a stored payment method for a specific amount from your server and capture it separately.

merchantApiServerPaymentMethodTransactionAuthorizationSessionStart

Start an authorization-only session against a stored payment method.

mutation StartServerAuthSession(
  $providerId: String
  $provider: TRANSACTION_PROVIDER
  $data: MerchantApiServerPaymentMethodTransactionAuthorizationSessionStartSchema!
) {
  merchantApiServerPaymentMethodTransactionAuthorizationSessionStart(
    merchantTransactionProviderId: $providerId
    transactionProvider: $provider
    data: $data
  ) {
    session {
      id
      status
      providerCode
    }
    transactions {
      id
      action
      status
      providerCode
      providerAuthorizationCode
    }
  }
}

This mutation returns a MerchantClientTransactionSessionContext — the authorization session and the resulting transactions (plus customer, paymentMethod, transactionProvider) are nested fields, not top-level.

Top-level arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	One of the two	AccruPay provider record ID
transactionProvider	TRANSACTION_PROVIDER	One of the two	Provider enum
data	schema	Yes	Authorization session details

data fields

Field	Type	Required	Description
merchantCustomerPaymentMethodId	String	Yes	AccruPay stored payment method UUID
merchantInternalTransactionCode	String	Yes	Your idempotency key / order ID
amount	BigInt	Yes	Amount to authorize in smallest currency unit
currency	CURRENCY	Yes	Currency enum
billing	BillingDataSchema	Yes	Billing details

---

merchantApiServerPaymentMethodTransactionAuthorizationSessionVerify

Verify and finalize the authorization session started above.

mutation VerifyServerAuthSession(
  $id: String
  $merchantInternalTransactionCode: String
  $providerCode: String
) {
  merchantApiServerPaymentMethodTransactionAuthorizationSessionVerify(
    id: $id
    merchantInternalTransactionCode: $merchantInternalTransactionCode
    providerCode: $providerCode
  ) {
    session {
      id
      status
      providerCode
    }
    transactions {
      id
      action
      status
      providerCode
      providerAuthorizationCode
    }
  }
}

Returns a MerchantClientTransactionSessionContext (same shape as start).

Provide at least one of id, merchantInternalTransactionCode, or providerCode to identify the session.

Arguments

Argument	Type	Required	Description
id	String	One of three	AccruPay session UUID
merchantInternalTransactionCode	String	One of three	Your order / transaction ID
providerCode	String	One of three	Provider's reference code

warning

This mutation does not accept a session token. Unlike client-side session verification, server authorization session verification uses id, merchantInternalTransactionCode, or providerCode as the identifier. Passing a client session token here will fail.

Once verified, use merchantApiTransactionAuthorizationSettle to capture the funds.

---

Optional input objects

In addition to billing, every payment-create and session-start input accepts three optional objects — shipping, device, and user. They are used for fraud signals, fulfillment, and end-user identity, and are passed in the same data object as billing. These are the canonical definitions; other pages link here.

ShippingDataSchema

Field	Type	Required	Description
shippingFirstName	String	Yes	Recipient first name
shippingLastName	String	Yes	Recipient last name
shippingEmail	String	Yes	Recipient email
shippingAddressCountry	COUNTRY_ISO_2	Yes	ISO 3166-1 alpha-2 country code
shippingPhone	String	No	Recipient phone
shippingAddressLine1	String	No	Street address line 1
shippingAddressLine2	String	No	Street address line 2
shippingAddressCity	String	No	City
shippingAddressState	String	No	State / region (ISO 3166-2 subdivision, e.g. NY)
shippingAddressPostalCode	String	No	Postal code

DeviceDataSchema

All fields optional. Used for device fingerprinting / fraud scoring.

Field	Type	Description
deviceType	DEVICE_TYPE	Device classification — see Enums
deviceBrowser	String	Browser identifier
deviceId	String	Your device identifier
deviceIp	String	Device IP address
deviceName	String	Device name
deviceOS	String	Operating system

UserDataSchema

End-user identity (distinct from billing). Required fields apply only when the user object is provided.

Field	Type	Required	Description
userFirstName	String	Yes	End-user first name
userLastName	String	Yes	End-user last name
userEmail	String	Yes	End-user email
userAddressCountry	COUNTRY_ISO_2	Yes	ISO 3166-1 alpha-2 country code
userPhone	String	No	End-user phone
userBirthDate	DateTimeISO	No	Date of birth
userLocale	String	No	Locale
userLegalIdentifier	String	No	Legal identifier (e.g. tax/national ID)
userLegalIdentifierType	String	No	Type of the legal identifier
userAddressLine1	String	No	Street address line 1
userAddressLine2	String	No	Street address line 2
userAddressCity	String	No	City
userAddressState	String	No	State / region (ISO 3166-2 subdivision)
userAddressPostalCode	String	No	Postal code

---

Related

• Authorizations — settle or void an authorized transaction
• Errors — transaction status vs API errors
• Reconciliation