chargePaymentMethod · ClientLoop Docs

mutation chargePaymentMethodAuthenticated

Charges a stored payment method. A refusal by the provider is reported in the result rather than raised as an error, so check success before reading payment. The method must be Active — charging an Expired, Invalid or deleted method fails. Supply an idempotencyKey so a retried request does not charge the customer twice.

Returns ChargePaymentMethodResult!

Arguments

Argument	Type	Description
`input`	`ChargePaymentMethodInput!`

Example request

curl -X POST 'https://graph.clientloop.com/' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api-key>' \
  -d '{
    "query": "mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) { chargePaymentMethod(input: $input) { success message payment { id orgId provider configurationId originalAmount amount currency status date expectedSettlementDate expectedFundsAvailableDate source { name connectionId orderId invoiceId invoiceNumber transactionId contactId contactName contactEmail } contactId paymentSessionId paymentPlanId paymentMethodId paymentMethod { id orgId contactId type status provider configurationId supportedRecurringProcessingModels paymentSessionId deletedAt createdAt updatedAt } recurringProcessingModel paymentSession { id orgId status amount currency callbackUrl successUrl link contactId transactionRef invoiceIds expirationDate paymentId createdAt updatedAt checkoutConfigurationId invoiceTotal brandLogoUrl brandName storePaymentMethod recurringProcessingModel storePaymentMethodResult paymentMethodId } } } }",
    "variables": {
      "input": {
        "orgId": "abc123",
        "paymentMethodId": "abc123",
        "amount": "100.00",
        "currency": "USD"
      }
    }
  }'

const response = await fetch('https://graph.clientloop.com/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <api-key>',
  },
  body: JSON.stringify({
    query: `
      mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) {
        chargePaymentMethod(input: $input) {
          success
          message
          payment {
            id
            orgId
            provider
            configurationId
            originalAmount
            amount
            currency
            status
            date
            expectedSettlementDate
            expectedFundsAvailableDate
            source {
              name
              connectionId
              orderId
              invoiceId
              invoiceNumber
              transactionId
              contactId
              contactName
              contactEmail
            }
            contactId
            paymentSessionId
            paymentPlanId
            paymentMethodId
            paymentMethod {
              id
              orgId
              contactId
              type
              status
              provider
              configurationId
              supportedRecurringProcessingModels
              paymentSessionId
              deletedAt
              createdAt
              updatedAt
            }
            recurringProcessingModel
            paymentSession {
              id
              orgId
              status
              amount
              currency
              callbackUrl
              successUrl
              link
              contactId
              transactionRef
              invoiceIds
              expirationDate
              paymentId
              createdAt
              updatedAt
              checkoutConfigurationId
              invoiceTotal
              brandLogoUrl
              brandName
              storePaymentMethod
              recurringProcessingModel
              storePaymentMethodResult
              paymentMethodId
            }
          }
        }
      }
    `,
    variables: {
      "input": {
        "orgId": "abc123",
        "paymentMethodId": "abc123",
        "amount": "100.00",
        "currency": "USD"
      }
    },
  }),
});

const { data, errors } = await response.json();

<?php

$body = <<<'JSON'
{
  "query": "mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) { chargePaymentMethod(input: $input) { success message payment { id orgId provider configurationId originalAmount amount currency status date expectedSettlementDate expectedFundsAvailableDate source { name connectionId orderId invoiceId invoiceNumber transactionId contactId contactName contactEmail } contactId paymentSessionId paymentPlanId paymentMethodId paymentMethod { id orgId contactId type status provider configurationId supportedRecurringProcessingModels paymentSessionId deletedAt createdAt updatedAt } recurringProcessingModel paymentSession { id orgId status amount currency callbackUrl successUrl link contactId transactionRef invoiceIds expirationDate paymentId createdAt updatedAt checkoutConfigurationId invoiceTotal brandLogoUrl brandName storePaymentMethod recurringProcessingModel storePaymentMethodResult paymentMethodId } } } }",
  "variables": {
    "input": {
      "orgId": "abc123",
      "paymentMethodId": "abc123",
      "amount": "100.00",
      "currency": "USD"
    }
  }
}
JSON;

$ch = curl_init('https://graph.clientloop.com/');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Authorization: Bearer <api-key>',
  ],
  CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var body = """
{
  "query": "mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) { chargePaymentMethod(input: $input) { success message payment { id orgId provider configurationId originalAmount amount currency status date expectedSettlementDate expectedFundsAvailableDate source { name connectionId orderId invoiceId invoiceNumber transactionId contactId contactName contactEmail } contactId paymentSessionId paymentPlanId paymentMethodId paymentMethod { id orgId contactId type status provider configurationId supportedRecurringProcessingModels paymentSessionId deletedAt createdAt updatedAt } recurringProcessingModel paymentSession { id orgId status amount currency callbackUrl successUrl link contactId transactionRef invoiceIds expirationDate paymentId createdAt updatedAt checkoutConfigurationId invoiceTotal brandLogoUrl brandName storePaymentMethod recurringProcessingModel storePaymentMethodResult paymentMethodId } } } }",
  "variables": {
    "input": {
      "orgId": "abc123",
      "paymentMethodId": "abc123",
      "amount": "100.00",
      "currency": "USD"
    }
  }
}
""";

var request = HttpRequest.newBuilder(URI.create("https://graph.clientloop.com/"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer <api-key>")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

using System.Net.Http;
using System.Text;

var body = """
{
  "query": "mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) { chargePaymentMethod(input: $input) { success message payment { id orgId provider configurationId originalAmount amount currency status date expectedSettlementDate expectedFundsAvailableDate source { name connectionId orderId invoiceId invoiceNumber transactionId contactId contactName contactEmail } contactId paymentSessionId paymentPlanId paymentMethodId paymentMethod { id orgId contactId type status provider configurationId supportedRecurringProcessingModels paymentSessionId deletedAt createdAt updatedAt } recurringProcessingModel paymentSession { id orgId status amount currency callbackUrl successUrl link contactId transactionRef invoiceIds expirationDate paymentId createdAt updatedAt checkoutConfigurationId invoiceTotal brandLogoUrl brandName storePaymentMethod recurringProcessingModel storePaymentMethodResult paymentMethodId } } } }",
  "variables": {
    "input": {
      "orgId": "abc123",
      "paymentMethodId": "abc123",
      "amount": "100.00",
      "currency": "USD"
    }
  }
}
""";

using var client = new HttpClient();
using var content = new StringContent(body, Encoding.UTF8, "application/json");
client.DefaultRequestHeaders.Add("Authorization", "Bearer <api-key>");

var response = await client.PostAsync("https://graph.clientloop.com/", content);
var result = await response.Content.ReadAsStringAsync();

EnvironmentAPI key *Operation

mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) {
  chargePaymentMethod(input: $input) {
    success
    message
    payment {
      id
      orgId
      provider
      configurationId
      originalAmount
      amount
      currency
      status
      date
      expectedSettlementDate
      expectedFundsAvailableDate
      source {
        name
        connectionId
        orderId
        invoiceId
        invoiceNumber
        transactionId
        contactId
        contactName
        contactEmail
      }
      contactId
      paymentSessionId
      paymentPlanId
      paymentMethodId
      paymentMethod {
        id
        orgId
        contactId
        type
        status
        provider
        configurationId
        supportedRecurringProcessingModels
        paymentSessionId
        deletedAt
        createdAt
        updatedAt
      }
      recurringProcessingModel
      paymentSession {
        id
        orgId
        status
        amount
        currency
        callbackUrl
        successUrl
        link
        contactId
        transactionRef
        invoiceIds
        expirationDate
        paymentId
        createdAt
        updatedAt
        checkoutConfigurationId
        invoiceTotal
        brandLogoUrl
        brandName
        storePaymentMethod
        recurringProcessingModel
        storePaymentMethodResult
        paymentMethodId
      }
    }
  }
}

Variables (JSON)

Types

input ChargePaymentMethodInput

Details of a payment to run against a stored payment method. The currency must match the currency the method was stored under.

Field	Type	Description
`orgId`	`ID!`	Organization that owns the payment method.
`paymentMethodId`	`ID!`	Id of the stored payment method to charge, as returned in PaymentMethod.id.
`amount`	`Amount!`	Amount to charge. Ex. 100.10. Must be greater than zero.
`currency`	`Currency!`	Three letter ISO currency code. Ex. USD
`recurringProcessingModel`	`RecurringProcessingModel`	How this payment is declared to the card networks. Defaults to UnscheduledCardOnFile, which covers a payment you initiate that follows no fixed schedule. Use Subscription when the payments run on a fixed interval, whatever the amount, and CardOnFile when the customer is present and started this payment themselves from your own checkout. The choice decides how the payment is treated for Strong Customer Authentication, so it should describe the arrangement you actually have with the customer.
`callbackUrl`	`URL`	URL to receive payment events for the resulting payment.
`transactionRef`	`String`	Optional merchant supplied reference ID for the transaction external to the platform.
`invoiceIds`	`[String!]`	Optional array of invoice IDs this charge settles. You cannot provide both invoiceIds and invoiceRefs.
`invoiceRefs`	`[PaymentSessionInvoiceRefInput!]`	Optional array of invoice references this charge settles. You cannot provide both invoiceIds and invoiceRefs.
`idempotencyKey`	`String`	Optional caller-supplied key that makes the charge idempotent. Repeating a call with the same key and org returns the payment created by the first call instead of charging again. Strongly recommended: without it a retried request charges the customer twice.

type ChargePaymentMethodResult

Outcome of charging a stored payment method. A refusal is a normal result rather than an error: success is false, message carries the provider's reason, and payment is null.

Field	Type	Description
`success`	`Boolean!`	Whether the charge was authorized.
`message`	`String`	The provider's refusal reason when success is false; null on success.
`payment`	`Payment`	The payment created by an authorized charge; null when the charge was refused.

scalar Amount

A monetary amount with up to two decimal places. Ex. 111.11

scalar Currency

Three letter ISO 4217 currency code. Ex. USD

enum RecurringProcessingModel

How a stored payment method may be used for a later payment, following the card networks' stored-credential framework. The model is declared when a method is stored and again on every payment made from it, and it decides how that later payment is treated for Strong Customer Authentication: a Subscription or UnscheduledCardOnFile charge is one you initiate and falls outside SCA, while a CardOnFile charge does not.

What separates the two models you initiate is the schedule, not the amount. A run of payments on a fixed interval is a Subscription even when the amount differs every time.

CardOnFile — Details kept so a returning customer checks out faster, where the later payment is one the customer starts themselves — a "pay with my saved card" button in your own checkout, for example.
Subscription — You initiate the payment, and the payments follow a fixed schedule the customer agreed to in advance. The amount may be fixed or may vary from one charge to the next: a monthly invoice whose total changes every month is still a subscription, because it is the interval that is fixed.
UnscheduledCardOnFile — You initiate the payment, and the payments follow no fixed schedule. For example a top-up triggered by a balance falling below a threshold, or an invoice raised whenever a job is finished.

scalar URL

A URL with protocol and port. ex. https://example.com

input PaymentSessionInvoiceRefInput

Merchant provided invoice detail used to create a payment session.

Field	Type	Description
`orderId`	`String`	The merchant provided order identifier.
`invoiceId`	`String`	The merchant provided invoice identifier.
`invoiceNumber`	`String`	The merchant provided invoice number.
`amount`	`Amount`	The total amount of the invoice. Ex 999.99
`lines`	`[PaymentSessionInvoiceLineItemRefInput!]`	The line items inside the merchant provided invoice.
`billingContact`	`PaymentSessionContactRefInput`	Billing contact information associated with the invoice
`shippingContact`	`PaymentSessionContactRefInput`	Shipping contact information associated with the invoice

type Payment

Field	Type	Description
`id`	`ID!`	Unique id of the payment (a bare KSUID).
`orgId`	`ID`	The platform organization that facilitated this payment.
`provider`	`PaymentProvider`	Payment provider that was used to process this payment
`configurationId`	`ID`	ID of the payment provider configuration that facilitated this payment
`originalAmount`	`Amount!`	Original amount for the payment. If this payment has only been authorized and is in a pending state this will be the amount authorized for the payment.
`amount`	`Amount!`	Amount of the payment. This may differ from the orginal amount if the captured payment amount is different than the authorized amount.
`currency`	`Currency!`	Currency of the payment
`status`	`PaymentStatus!`	Status of the payment
`date`	`DateTime!`	The date the payment was created. If payments are pre-created pending, this date will be updated when the payment is actually completed.
`expectedSettlementDate`	`String`	The estimates date funds will be settled.
`expectedFundsAvailableDate`	`String`	The estimated date funds will be available to the merchant.
`source`	`PaymentSource`	Integration source details for this payment.
`contactId`	`ID`	Optional ID of the platform contact associated with this payment.
`paymentSessionId`	`ID`	ID of the payment session that facilitated this payment
`paymentPlanId`	`ID`	ID of the payment plan that generated this payment
`paymentMethodId`	`ID`	ID of the stored payment method that was charged to create this payment. Null when the payment did not come from a stored method.
`paymentMethod`	`PaymentMethod`	Stored payment method that was charged to create this payment. Null when the payment did not come from a stored method.
`recurringProcessingModel`	`RecurringProcessingModel`	How this payment was declared to the card networks. Set on a payment made from a stored method and on the payment that stored one; null otherwise. Kept on the record so a disputed charge, or an audit of how a series was declared, can be answered from the payment itself.
`paymentSession`	`PaymentSession`	Payment session that facilitated this payment

input PaymentSessionInvoiceLineItemRefInput

Merchant provided invoice line item detail used to create a payment session.

Field	Type	Description
`num`	`Int!`	Line number in the invoice. This is used to order the line items for display.
`quantity`	`Float`	Number of units of the product.
`price`	`Amount`	The price of the product. Ex. 100.10 Note that the currency used is from the PaymentSession.
`productId`	`String`	The ID of the product.
`productSku`	`String`	The sku of the product.
`productName`	`String`	The name of the product. This may or may not be displayed to the customer depending on the layout templated selected and its configuration.
`productDescription`	`String`	The description of the product. This may or may not be displayed to the customer depending on the layout templated selected and its configuration.
`productImageUrl`	`URL`	The URL to the product image to show to the customer. This may or may not be displayed to the customer depending on the layout templated selected and its configuration.

input PaymentSessionContactRefInput

Merchant provide contact information to use when creating a payment session.

Field	Type	Description
`contactId`	`ID`
`contactName`	`String`
`contactFirstName`	`String`
`contactLastName`	`String`
`contactEmail`	`Email`
`contactPhone`	`Phone`
`address`	`GlobalAddressInput`

enum PaymentProvider

NMI
Plaid
CLP

enum PaymentStatus

Pending
Completed
Finalized
Canceled

scalar DateTime

ISO 8601 formatted date time. Ex. 2023-11-23T14:30:00Z

type PaymentSource

The source of the payment. This is used to identify the integration and specific connection that facilitated the payment within the integration.

Field	Type	Description
`name`	`String`	Name of the integration that facilitated this payment. This is typically the name of the integration that's using the checkout process like an ecommerce platform or CRM.
`connectionId`	`ID`	The ID of the connection within the integration that facilitated this payment.
`orderId`	`String`	Optional merchant supplied order ID associated with the payment.
`invoiceId`	`String`	Optional merchant supplied invoice ID associated with the payment.
`invoiceNumber`	`String`	Optional merchant supplied invoice number associated with the payment.
`transactionId`	`String`	Optional merchant supplied transaction ID associated with the payment.
`contactId`	`String`	Optional merchant supplied contact ID for which this payment session is attached.
`contactName`	`String`	Optional merchant supplied contact name for which this payment session is attached.
`contactEmail`	`String`	Optional merchant supplied contact email for which this payment session is attached.

type PaymentMethod

A payment instrument stored against a contact so it can be charged again without the customer re-entering it.

A payment method is created by completing a payment session whose storePaymentMethod was not Disabled, and charged afterwards with chargePaymentMethod. Payment options that are unsuitable for storing are not offered during such a session — consumer financing such as FlexPay, for example, applies to a single purchase and cannot act as a method on file.

Field	Type	Description
`id`	`ID!`	Globally unique id of the payment method, a KSUID behind the `pmd` category prefix. Treat it as opaque: the prefix exists so the server can route the id to this type, and its format is not part of the contract. Refetchable through the Relay `node(id:)` query as well as `paymentMethod(id:)`.
`orgId`	`ID!`	Organization that owns this payment method.
`contactId`	`ID!`	ID of the contact this payment method is stored against.
`contact`	`Contact`	Contact this payment method is stored against.
`type`	`PaymentMethodType!`	Whether this method is a card or a bank account. Determines which of `card` and `bankAccount` is populated.
`status`	`PaymentMethodStatus!`	Whether the method can still be charged.
`provider`	`PaymentProvider!`	Payment provider holding the underlying credential.
`configurationId`	`ID`	ID of the provider configuration the credential is stored under. Charges against this method run through the same configuration.
`card`	`PaymentMethodCard`	Card detail. Populated when type is Card, otherwise null.
`bankAccount`	`PaymentMethodBankAccount`	Bank account detail. Populated when type is BankAccount, otherwise null.
`supportedRecurringProcessingModels`	`[RecurringProcessingModel!]!`	The ways this method may be used for a later payment. A method is stored under the model declared on its payment session, and the provider reports which models the resulting credential supports. Read it before offering a customer a subscription against a method that may not carry one.
`billingAddress`	`GlobalAddress`	Billing address captured alongside the instrument.
`paymentSessionId`	`ID`	ID of the payment session that stored this payment method.
`deletedAt`	`DateTime`	Set when the payment method has been deleted; null while it is usable. A deleted method is excluded from `Contact.paymentMethods` unless `includeDeleted` is set, and can no longer be charged.
`createdAt`	`DateTime!`	Date the payment method was stored.
`updatedAt`	`DateTime!`	Date the payment method was last updated.

type PaymentSession

Represents a payment session a customer can use to make a payment. This session is used to configuration and setup the payment experience for an individual customer's session during checkout.

Field	Type	Description
`id`	`ID!`	Unique identifier for the payment session.
`orgId`	`ID!`	Organization identifier the payment session belongs to.
`status`	`PaymentSessionStatus!`	Status of the payment session.
`amount`	`Amount!`	Total payment amount. Ex. 100.10. Zero when the session only stores a payment method, in which case the instrument is validated and stored and no payment is taken. A zero amount goes with storePaymentMethod Enabled.
`currency`	`Currency!`	Three letter ISO currency code. Ex. USD
`callbackUrl`	`URL`	URL to receive payment session events
`successUrl`	`URL`	URL to redirect after a payment session is completed by the customer
`link`	`URL`	Link to the payment session. This will be null if the session is expired or completed. This link is used to redirect the user to the payment page or may be used to embedded payment flow depending on the configuration provided.
`contactId`	`ID`	ID for the contact for which this payment session is attached. Always present when storePaymentMethod is anything but Disabled, since a payment method is stored against a contact.
`contact`	`Contact`	Contact for which this payment session is attached.
`contactRef`	`PaymentSessionContactRef`	Optional merchant supplied reference contact information external to the platform.
`transactionRef`	`String`	Optional merchant supplied reference ID for the transaction external to the platform.
`invoiceIds`	`[String!]`	Optional array of invoice IDs which this payment session is attached to. You cannot provide both invoiceIds and invoiceRefs. Note that some feature are unavailable unless at least one invoiceId or invoiceRef is provided.
`invoiceRefs`	`[PaymentSessionInvoiceRef!]`	Optional array of invoice references which this payment session is attached to. You cannot provide both invoiceIds and invoiceRefs. Note that some features are unavailable unless at least one invoiceId or invoiceRef is provided.
`expirationDate`	`DateTime`	Optional expiration date for the payment session. ISO 8601 format.
`paymentId`	`ID`	Payment ID associated with this payment session. If the payment session status is completed, this will be populated. It may also be populated if the payment session was attached to a pre-created payment record.
`createdAt`	`DateTime!`	Date the payment session was created
`updatedAt`	`DateTime!`	Date the payment session was last updated
`checkoutConfigurationId`	`ID`	The checkout configuration ID used for this payment session.
`invoiceTotal`	`Amount`	Optional total amount due across the referenced invoices. When the payment amount exceeds this total (for example because of a surcharge or tip), financing options such as FlexPay are disabled since they cannot finance the additional amount.
`brandLogoUrl`	`URL`	Optional caller-supplied URL to a logo image to display during checkout, overriding the default branding.
`brandName`	`String`	Optional caller-supplied brand or merchant name to display during checkout, overriding the organization name.
`storePaymentMethod`	`StorePaymentMethodMode!`	Whether the payment method the customer enters is stored against the session's contact for future use, and whether the customer is asked first. Defaults to Disabled.
`recurringProcessingModel`	`RecurringProcessingModel`	How a method stored by this session is declared to the card networks when it is charged later. Null when storePaymentMethod is Disabled.
`storePaymentMethodResult`	`StorePaymentMethodResult!`	What became of the request to store the payment method. NotAttempted until the session completes, and always NotAttempted when storePaymentMethod is Disabled. A null paymentMethodId has three causes; this field says which.
`paymentMethodId`	`ID`	ID of the payment method stored by this session. Populated when storePaymentMethodResult is Stored; null otherwise.
`paymentMethod`	`PaymentMethod`	Payment method stored by this session. Populated when storePaymentMethodResult is Stored; null otherwise.

scalar Email

An email address

scalar Phone

E.164 formatted phone number. Ex. +14155554345

input GlobalAddressInput

Address of a physical location

Field	Type	Description
`lines`	`[String!]!`	Street, unit, building number, etc.
`locality`	`String`	City, town or municipality designation
`administrativeArea`	`String`	State, province or area designation
`postalCode`	`String`	Postal code or ZIP code
`countryCode`	`String!`	2-letter country code. Ex. USA

type Contact

Field	Type	Description
`id`	`ID!`	Unique ID of the contact.
`orgId`	`ID!`	ID of the organization that owns the contact.
`ownerId`	`ID!`	Global ID of the owning organization (`Org#<id>`). Deprecated; use `orgId`. Deprecated: Use `orgId` instead.
`name`	`String!`	Full name of the contact.
`givenName`	`String`	Given name of the contact.
`familyName`	`String`	Family name of the contact.
`email`	`Email`	Email address of the contact.
`phone`	`Phone`	Phone number of the contact. This will be validated and normalized to the E.164 format.
`deletedAt`	`String`	Set when the contact has been soft-deleted; null for an active contact.
`createdAt`	`String!`	Date and time when the contact was created.
`updatedAt`	`String!`	Date and time when the contact was last updated.
`idv`	`ContactIdvSessionDetail`	The latest Plaid identity-verification session for this contact. On the public graph this exposes the session timestamps, the captured selfie video, the captured identity documents, and the individual check outcomes; the remaining detail is private-graph only. Null when the contact has never started a session. Fetched on demand from Plaid — request it only when needed.
`paymentMethods`(input)	`PaymentMethodConnection!`	Payment methods stored against this contact, as a Relay-style, cursor-paginated connection, newest first. Page forward by starting with first: N, then passing the previous response's pageInfo.endCursor back as after (repeat while pageInfo.hasNextPage); page backward with last + before. Deleted methods are omitted unless includeDeleted is set.

enum PaymentMethodType

The kind of instrument a stored payment method holds.

Card — A credit or debit card.
BankAccount — A bank account debited over ACH.

enum PaymentMethodStatus

Whether a stored payment method can still be charged.

Active — Usable for new payments.
Expired — Past its expiration date. Charges will be declined until the customer stores a new method.
Invalid — The provider no longer accepts the stored credential, for example because the card was reported lost or the bank account was closed.

type PaymentMethodCard

Card detail for a stored payment method whose type is Card.

Field	Type	Description
`brand`	`String`	Card brand as reported by the provider. Ex. Visa
`last4`	`String!`	Last four digits of the card number.
`expirationMonth`	`Int!`	Expiration month, 1-12.
`expirationYear`	`Int!`	Expiration year, four digits. Ex. 2029
`cardholderName`	`String`	Name on the card as captured when the method was stored.
`funding`	`PaymentMethodCardFunding!`	Whether the card draws on a credit, debit or prepaid account. Surcharging rules turn on this distinction. It can only be captured from the provider's response at the moment the method is stored, never looked up afterwards, and some providers report it only when the merchant's account is configured to include it, so a method stored without it stays Unknown for life.

type PaymentMethodBankAccount

Bank account detail for a stored payment method whose type is BankAccount.

Field	Type	Description
`institutionName`	`String`	Name of the institution holding the account. Ex. Chase. Depends on the provider: reported for accounts linked through Plaid, and generally absent for accounts stored directly with the card processor, which does not return it.
`accountHolderName`	`String`	Name on the account as reported by the provider.
`last4`	`String`	Last four digits of the account number.
`accountType`	`PaymentMethodBankAccountType`	Whether the account is a checking or savings account.

type GlobalAddress

Address of a physical location

Field	Type	Description
`lines`	`[String!]!`	Street, unit, building number, etc.
`locality`	`String`	City, town or municipality designation
`administrativeArea`	`String`	State, province or area designation
`postalCode`	`String`	Postal code or ZIP code
`countryCode`	`String!`	2-letter country code. Ex. USA

enum PaymentSessionStatus

Expired
Active
Completed
Canceled

type PaymentSessionContactRef

Merchant provide contact information for use during a payment session.

Field	Type	Description
`contactId`	`ID`
`contactName`	`String`
`contactFirstName`	`String`
`contactLastName`	`String`
`contactEmail`	`Email`
`contactPhone`	`Phone`
`address`	`GlobalAddress`

type PaymentSessionInvoiceRef

Merchant provided invoice information for use during a payment session.

Field	Type	Description
`orderId`	`String`	The merchant provided order identifier.
`invoiceId`	`String`	The merchant provided invoice identifier.
`invoiceNumber`	`String`	The merchant provided invoice number.
`amount`	`Amount`	The total amount of the invoice. Ex 999.99
`lines`	`[PaymentSessionInvoiceLineItemRef!]`	The line items inside the merchant provided invoice.
`billingContact`	`PaymentSessionContactRef`	Billing contact information associated with the invoice
`shippingContact`	`PaymentSessionContactRef`	Billing contact information associated with the invoice

enum StorePaymentMethodMode

Whether a payment session stores the payment method the customer enters against its contact, and whether the customer gets a say in it.

Disabled — Nothing is stored. The default.
AskForConsent — Checkout offers the customer the choice of saving their details and stores the method only if they accept. Payment options that are unsuitable for storing stay available, since the customer may decline and pay with one; no saving is offered for those options.
Enabled — The method is stored as a condition of paying, and checkout tells the customer so rather than asking. Payment options that are unsuitable for storing are withdrawn from the session.

enum StorePaymentMethodResult

What became of a payment session's request to store the payment method, once the session completed.

NotAttempted — No store was attempted: storePaymentMethod was Disabled, or the session has not completed.
Declined — The customer declined to save their details under AskForConsent.
Refused — The provider rejected the credential and nothing was stored. Under Enabled, where storing is a condition of paying, no payment was taken either; paymentId reports whether one was taken in any other case.
Stored — The method was stored, and paymentMethodId identifies it.

type ContactIdvSessionDetail

Details of a contact's Plaid identity-verification session, fetched on demand from Plaid. The public graph exposes the timestamps, the captured selfie video, the captured identity documents, and the individual check outcomes; the remaining fields — including the raw Plaid pass-throughs they are derived from — are private-graph only.

Field	Type	Description
`status`	`ContactIdvSessionStatus!`	Where the verification as a whole stands. Success, Failed and PendingReview are all terminal and all carry captured identity; Active is still in progress, and Expired or Canceled never produced one.
`createdAt`	`DateTime!`
`completedAt`	`DateTime`
`documents`	`[ContactIdvDocument!]!`	Captured identity documents, pulled out of documentary_verification: each document's category and its captured images.
`selfieVideoUrl`	`String`	URL of the captured selfie video, pulled out of selfieCheck for direct access. Plaid-hosted and expiring; null when the template did not capture a selfie video.
`nameMatch`	`IdvMatchSummary`	How the name that the contact supplied compared against Plaid's data sources. Null when the KYC step has not run.
`dateOfBirthMatch`	`IdvMatchSummary`	How the date of birth compared against Plaid's data sources. Null when the KYC step has not run.
`phoneNumberMatch`	`IdvMatchSummary`	How the phone number compared against Plaid's data sources. Null when the KYC step has not run.
`addressMatch`	`IdvMatchSummary`	How the address compared against Plaid's data sources. Null when the KYC step has not run.
`taxIdMatch`	`IdvMatchSummary`	How the tax id (SSN) compared against Plaid's data sources, from Plaid's id_number check. Null when the KYC step has not run.
`livenessCheck`	`IdvLivenessStatus`	Whether the captured selfie passed liveness detection. Null when the selfie step has not run or captured no analysis.
`facialComparisonCheck`	`IdvFacialComparisonStatus`	Whether the captured selfie matched the face on the identity document. Null when the selfie step has not run or captured no analysis.

type PaymentMethodConnection

A page of payment methods following the Relay Connection spec. edges holds the payment methods in this page (each with its cursor) and pageInfo describes whether more pages exist in each direction plus the cursors that bound this page.

Field	Type	Description
`edges`	`[PaymentMethodEdge!]!`	The payment methods in this page, ordered newest first.
`pageInfo`	`PageInfo!`	Pagination metadata for this page: hasNextPage/hasPreviousPage and the startCursor/endCursor bounds.

input PaymentMethodsInput

Filter and pagination for a payment methods connection.

Pagination is Relay cursor-based, not page/offset based — see the Relay Connections spec. Page forward with first + after, or backward with last + before; never mix the two directions in a single call. Cursors are opaque strings taken from a previous response's pageInfo (or edges[].cursor) — treat them as black boxes, don't build or parse them yourself.

Field	Type	Description
`first`	`Int`	Forward pagination: return at most the first N payment methods from the start of the result window. Pair with after to walk forward. Do not combine with last/before. When omitted (and no last), a default page size is used.
`after`	`String`	Forward pagination cursor: return the payment methods that come after this cursor. Use the pageInfo.endCursor from the previous page. Pair with first.
`last`	`Int`	Backward pagination: return at most the last N payment methods nearest the end of the result window. Pair with before to walk backward. Do not combine with first/after.
`before`	`String`	Backward pagination cursor: return the payment methods that come before this cursor. Use the pageInfo.startCursor from the previous page. Pair with last.
`type`	`PaymentMethodType`	Return only methods of this kind. Omit to return both cards and bank accounts.
`status`	`PaymentMethodStatus`	Return only methods in this state. Omit to return every state.
`includeDeleted`	`Boolean`	Include methods that have been deleted. Defaults to false, so deleted methods are omitted. Deleted methods can never be charged; include them only to render history.

enum PaymentMethodCardFunding

How a stored card funds a payment, when the provider reports it.

Credit
Debit
Prepaid
Unknown

enum PaymentMethodBankAccountType

The kind of bank account a stored payment method debits.

Checking
Savings

type PaymentSessionInvoiceLineItemRef

Merchant provided invoice line item information for use during a payment session.

Field	Type	Description
`num`	`Int!`
`quantity`	`Float`
`price`	`Amount`
`productId`	`String`
`productSku`	`String`
`productName`	`String`
`productDescription`	`String`
`productImageUrl`	`URL`

enum ContactIdvSessionStatus

Where a contact's verification stands. Mirrors the shared IdvSessionStatus but is declared separately so the contact graph's public surface does not depend on a type owned by the application module.

Active
Expired
Canceled
Success
Failed
PendingReview

type ContactIdvDocument

A captured identity document from a contact's Plaid documentary verification.

Field	Type	Description
`category`	`String`	Document category as classified by Plaid (e.g. drivers_license, id_card, passport). Null when Plaid could not classify the document.
`images`	`[ContactIdvDocumentImage!]!`	Captured images for this document (e.g. originalFront, croppedBack, face).

enum IdvMatchSummary

How one value that the contact supplied compared against the data sources that Plaid checked it against. NoData means Plaid held nothing to compare with; NoInput means the contact supplied nothing to compare.

Match
PartialMatch
NoMatch
NoData
NoInput

enum IdvLivenessStatus

Whether the captured selfie passed liveness detection — that a live person was present rather than a photograph or a screen.

Success
Failed

enum IdvFacialComparisonStatus

How the captured selfie compared against the face on the captured identity document. NoInput means one of the two was never captured.

Match
NoMatch
NoInput

type PaymentMethodEdge

A single element of a PaymentMethodConnection page: the payment method itself (node) plus the opaque cursor that points at it. Pass a cursor back as after (forward) or before (backward) to page relative to this row.

Field	Type	Description
`node`	`PaymentMethod!`	The payment method at this position in the page.
`cursor`	`String!`	Opaque cursor identifying this payment method's position, for use as after or before.

type PageInfo

PageInfo type for cursor-based pagination following the Relay specification for cursor based pagination.

Field	Type	Description
`hasNextPage`	`Boolean!`
`hasPreviousPage`	`Boolean!`
`startCursor`	`String`
`endCursor`	`String`

type ContactIdvDocumentImage

A single captured image belonging to a ContactIdvDocument. Plaid-hosted and expiring.

Field	Type	Description
`name`	`String`	Image identifier (e.g. originalFront, croppedBack, face).
`url`	`String`	Plaid-hosted URL of the image. Expires.