Version: Lab (preview)

Payment Method Token

Payment Method Tokens are meant to store info that represents a tokenized Bank Account, Credit Card, or Debit Card.

The Payment Method Token Object

{
  address_line1: String
  address_line2: String
  bank_account_type: AchAccountType
  bank_code: String
  barcode_id: String
  card_brand: String
  card_type: CardType
  city: String
  country: String
  exp_date: String
  full_name: String
  is_active: Boolean
  issuing_country_code: String
  last_four: String
  merchant_uid: String
  metadata: AWSJSON
  payment_method_id: String
  payment_type: PaymentType
  payor: Payor
  postal_code: String
  region: String
  wallet_type: WalletType
}

Key	type	description
address_line1	String	The first line of the billing address.
address_line2	String	The second line of the billing address.
bank_account_type	AchAccountType	The type of bank account.
bank_code	String	The bank code of the bank account if `payment_type` is `ACH`.
barcode_id	String	The barcode id of the payment method token if `payment_type` is `CASH`.
card_brand	String	The brand of the card if `payment_type` is `CARD`.
card_type	CardType	The type of card if `payment_type` is `CARD`.
city	String	The city of the billing address.
country	String	The country of the billing address.
exp_date	String	The expiration date of the card if `payment_type` is `CARD`. Format: `MMYY`
full_name	String	The name on card or bank account.
is_active	Boolean	Indicator for if payment method is active. If false the payment method cannot be used to process new transactions.
issuing_country_code	String	The issuing country code of the country that issued the card or that the bank account was opened in.
last_four	String	The last four digits of the card or bank account number.
merchant_uid	String	The Pay Theory unique identifier assigned to the merchant that the payment_method_token belongs to.
metadata	AWSJSON	Any additional data that was stored with the payment method token.
payment_method_id	String	The unique payment method id.
payment_type	PaymentType	The type of payment method. It can be one of the following: `CARD`, `ACH`
payor	Payor	The payor object. Refer to the Payor docs for more info.
postal_code	String	The postal code of the billing address.
region	String	The region of the billing address.
wallet_type	WalletType	The type of wallet that the payment method token is stored in.

Ach Account Type

The type of bank account. It can be one of the following:

BUSINESS_CHECKING
BUSINESS_SAVINGS
PERSONAL_CHECKING
PERSONAL_SAVINGS

Card Type

The type of card. It can be one of the following:

BUSINESS_CREDIT
BUSINESS_DEBIT
CREDIT_CARD
DEBIT_CARD
PREPAID_CARD

Payment Type

The type of payment method. It can be one of the following:

ACH
CARD
CASH

Wallet Type

The type of wallet that the payment method token is stored in. It can be one of the following:

APPLE_PAY
CLICK_TO_PAY
GOOGLE_PAY
SAMSUNG_PAY
VISA_STAGED

Query Payment Method Tokens

{
    paymentMethodTokens(direction: MoveDirection, limit: Int, offset: String, offset_id: String, query: SqlQuery) {
        items {
          address_line1
          address_line2
          card_brand
          city
          country
          exp_date
          full_name
          is_active
          last_four
          merchant_uid
          metadata(query_list: [QueryPair])
          payment_method_id
          payment_type
          payor(query_list: [QueryPair]) {
            ...
          }
          postal_code
          region
          wallet_type
        }
        total_row_count
    }
}

Parameters

Key	type	description
direction	MoveDirection	The direction of the pagination. Makes sure the results are returned in the correct order.
limit	Int	The number of payment_method_tokens to return.
offset	String	The value of the offset item for which the list is being sorted.
offset_id	String	The `payment_method_id` of the offset item.
query	SqlQuery	The query to filter the payment_method_tokens with based on Pay Theory defined data. Detailed information about the query object can be found here.

Nested Queries Payment Method Tokens can also be filtered by passing a query_list to the metadata or payor.

This will only return Payment Method Tokens that have Metadata or Payors that match these queries. Detailed information about the query list can be found here.

Returns

Key	type	description
items	[PaymentMethodToken]	The list of payment_method_tokens that are returned from the query.
total_row_count	Int	The total number of payment_method_tokens that match the query. Used to help with pagination.

Create Payment Method

This mutation will create a payment method token for a payor. The payment method token can be used to create a payment method for a merchant.

note

You must be PCI L1 compliant to use this mutation. For more details contact support@paytheory.com

mutation {
    createPaymentMethod(payment_method: PaymentMethodInput!,
                        merchant_uid: String!,
                        skip_validation: Boolean) {
        payment_method_id
        ...
    }
}

Parameters

Key	type	description
payment_method	PaymentMethodInput	The payment method input object. Refer to the PaymentMethodInput docs for more info.
merchant_uid	String	The Pay Theory unique identifier assigned to the merchant that the payment_method_token belongs to.
skip_validation	Boolean	A boolean flag indicating whether to skip the validation of the payment method. Defaults to `false` if not passed in.

Returns The payment method token object. Refer to the Payment Method Token for more info.

Payment Method Input Object

This is the input object used when passing in payment method into any mutation that requires it.

note

You must be PCI L1 compliant to use this in a mutation. For more details contact support@paytheory.com

{
    ach: AchInput
    card: CardInput
    canadian_eft: CanadianEftInput
    metadata: AWSJSON
    payor: PayorInput
    payor_id: String
}

Key	type	description
ach	AchInput	The ach input object used for creating Bank Accounts in the USA
card	CardInput	The card input object.
canadian_eft	CanadianEftInput	The canadian eft input object used for creating Bank Accounts in Canada.
metadata	AWSJSON	Any additional data that you want to store with the payment method token. This data will be returned with the payment method token when queried.
payor	PayorInput	The payor input object. Refer to the PayorInput docs for more info.
payor_id	String	The unique payor id for the payor this payment method token belongs to.

ACH Input Object

The ach input object. It contains the following fields:

{
    address_line1: String
    address_line2: String
    account_number: String!
    account_type: AchAccountType!
    city: String
    country: String
    name_on_account: String!
    postal_code: String
    region: String
    routing_number: String!
}

Key	type	description
address_line1	String	The first line of the billing address.
address_line2	String	The second line of the billing address.
account_number	String!	The account number of the bank account.
account_type	AchAccountType	The type of bank account.
city	String	The city of the billing address.
country	String	The country of the billing address.
name_on_account	String!	The name on the bank account.
postal_code	String	The postal code of the billing address.
region	String	The region of the billing address.
routing_number	String!	The routing number of the bank account.

Canadian EFT Input Object

The Canadian EFT input object. It contains the following fields:

{
  account_number: String!
  account_type: BankAccountType!
  institution_number: String!
  name_on_account: String!
  transit_number: String!
}

Key	type	description
account_number	String!	The account number of the bank account.
account_type	BankAccountType!	The type of bank account.
institution_number	String!	The institution number of the bank account. Should be 3 digits.
name_on_account	String!	The name on the bank account.
transit_number	String!	The transit number of the bank account. Should be 5 digits.

Card Input Object

The card input object. It contains the following fields:

{
    address_line1: String
    address_line2: String
    card_number: String!
    city: String
    country: String
    exp_date: CardExpirationInput!
    full_name: String
    postal_code: String!
    region: String
    security_code: String!
}

Key	type	description
address_line1	String	The first line of the billing address.
address_line2	String	The second line of the billing address.
card_number	String!	The card number.
city	String	The city of the billing address.
country	String	The country of the billing address.
exp_date	CardExpirationInput!	The card expiration input object. Refer to the CardExpirationInput docs for more info.
full_name	String	The name on the card.
postal_code	String!	The postal code of the billing address.
region	String	The region of the billing address.
security_code	String!	The security code of the card.

Card Expiration Input

The card expiration input object. It contains the following fields:

{
    month: String!
    year: String!
}

Key	type	description
month	String!	The month of the expiration date. Format: `MM`
year	String!	The year of the expiration date. Format: `YY`

Update Payment Method To Disabled

This mutation can be used to disable a payment method token. This will prevent the payment method token from being used to create a payment. Once a payment method token is disabled, it cannot be re-enabled.

mutation MyMutation {
  updatePaymentMethodToDisabled(merchant_uid: String!, payment_method_id: String!)
}

Parameters

Key	type	description
merchant_uid	String	The Pay Theory unique identifier assigned to the merchant that the payment_method_token belongs to.
payment_method_id	String	The unique payment method id.

Returns

{
  "data": {
    "updatePaymentMethodToDisabled": true
  }
}

Validate Payment Method Ownership

This mutation validates whether a provided card or bank account number matches a specific payment method.

note

You must be PCI L1 compliant to use this mutation. For more details contact support@paytheory.com

query {
  validatePaymentMethodOwnership(
    number: String!,
    payment_method_id: String!
  )
}

Parameters

Key	type	description
number	String	The card number or account number to validate. For card payment methods, this is the full card number. For ACH payment methods, this is the full account number.
payment_method_id	String	The unique payment method id that identifies the payment method to validate against.

Returns

A boolean value indicating whether the provided number matches the payment method:

true if the number matches the payment method
false if the number does not match the payment method

{
  "data": {
    "validatePaymentMethodOwnership": true
  }
}

The Payment Method Token Object​

Ach Account Type​

Card Type​

Payment Type​

Wallet Type​

Query Payment Method Tokens​

Create Payment Method​

Payment Method Input Object​

ACH Input Object​

Canadian EFT Input Object​

Card Input Object​

Card Expiration Input​

Update Payment Method To Disabled​

Validate Payment Method Ownership​

The Payment Method Token Object

Ach Account Type

Card Type

Payment Type

Wallet Type

Query Payment Method Tokens

Create Payment Method

Payment Method Input Object

ACH Input Object

Canadian EFT Input Object

Card Input Object

Card Expiration Input

Update Payment Method To Disabled

Validate Payment Method Ownership