Saved payment methods

The token the card or bank SDK gives you is short-lived and single-use. To charge the same card again next month, convert it into a payment method.

Token or payment method?

	SDK token	Payment method
Lifetime	Minutes	Until deleted
Reusable	No	Yes
Where it comes from	createTokenCallback in the browser	createPaymentMethod on your server
Use for	A one-off payment	Recurring billing, saved cards, "pay with the card on file"

Both are passed to createPayment as paymentMethodId, so the payment code is identical either way.

Headers

The standard three.

{
  "x-aptean-apim": "<your api key>",
  "x-aptean-tenant": "<your tenant id>",
  "x-aptean-tenant-secret": "<your tenant secret>"
}

Save a payment method

mutation CreatePaymentMethod($input: CreatePaymentMethodInput!) {
  createPaymentMethod(input: $input) {
    code
    message
    error
    paymentMethod {
      id
    }
  }
}

{
  "input": {
    "token": "<the token id from the SDK callback>",
    "attachToResourceId": "<the customer or person id to attach it to>",
    "isDefault": true
  }
}

Field	Type	Notes
token	String	Required. The id from the SDK's token callback.
attachToResourceId	String	Required. A payment method cannot exist unattached.
isDefault	Boolean	Make this the default for that resource.
shareWithMerchant	Boolean	Whether the merchant can use it, not just the payer.
customData	JSON	Arbitrary key–value pairs.

Warning

attachToResourceId is mandatory. There is no way to create a floating payment method and attach it afterwards — you must know who it belongs to at the point of saving. Decide your customer or person id before you call the SDK.

Warning

Do this promptly. The SDK token expires in minutes, so convert it on the same request that receives it. Do not queue it for a nightly job.

Attach an existing one to another resource

One saved card can belong to more than one resource — the same payer across two of your customer records, for instance.

mutation AttachPaymentMethod($input: AttachPaymentMethodInput!) {
  attachPaymentMethod(input: $input) {
    code
    message
    error
  }
}

{
  "input": {
    "paymentMethodId": "<the saved payment method id>",
    "resourceId": "<the resource to attach it to>",
    "isDefault": false
  }
}

Note

On attachPaymentMethod, isDefault is required, not optional — unlike on createPaymentMethod. Send it explicitly.

email and phone may also be supplied to update the holder's contact details at the same time.

Detach, update, delete

Mutation	Input	What it does
detachPaymentMethod	paymentMethodId, resourceId	Removes the link to one resource. The payment method itself survives.
updatePaymentMethod	paymentMethodId, resourceId, isDefault?, shareWithMerchant?	Changes the flags on an attachment.
deletePaymentMethod	paymentMethodId	Deletes the payment method outright, everywhere.

Warning

detachPaymentMethod and deletePaymentMethod are not the same thing. Detaching unlinks it from one resource; deleting destroys it for all of them. If you meant "this customer no longer uses this card", detach.

List what is saved

query {
  paymentMethods(
    resourceId: "<the resource id>"
    orderBy: { field: TIMESTAMP, direction: DESC }
    first: 20
  ) {
    nodes {
      id
      paymentMethodType
      status
    }
  }
}

paymentMethods also filters on customerId, id, emailId, paymentMethodType (credit-card or payment-bank-us), status and queryString, and pages with first/after/last/before.

Cards expire

A saved card is not permanent. The card behind it expires, gets reissued after fraud, or is cancelled. A payment against a saved method can decline for reasons that have nothing to do with your integration.

Handle the decline, tell the payer, and collect a fresh card through the SDK. Do not retry the same saved method in a loop — repeated declines can count against your merchant account.