Creates a customer. If payment method data is provided, ..

Tokenise Payment Method

Mutation

Client TokenPrivate Key

You can securely store a payment method in our vault. You should use our recommended payments integrations to perform this process client-side. This ensures that no sensitive card data touches your server, and allows your integration to operate in a PCI-compliant way. The payment method is tokenised and we return you a token for future use.

If a customer id is provided, it assigns the payment method to that customer.

If customer data is provided, it creates a new customer and assigns the payment method to that customer.

Request

ValueType

paymentMethodpaymentMethodInput ﹡
paymentMethod.cardPaymentCardInput
The card this token will represent
customerVaultCustomerInput
Customer details to associate to the token
customer.idString
Unique identifier for the customer
customer.billingAddressBillingAddressInput
The customer’s address
customer.descriptionString
An arbitrary string attached to the object
customer.emailString
The customer’s email address
customer.nameString ﹡
The customer’s full name or business name
customer.phoneString
The customer’s phone number
customer.shippingAddressShippingAddressInput
Mailing and shipping address for the customer
customer.companyCompanyInput
Company details for customer

CURL

JAVASCRIPT

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "mutation tokenisePaymentMethod($data: TokenInput!){
    tokenisePaymentMethod(data: $data) {
        id
        token
        createdDate
   }
 }",
	"variables": {
		"data": {
        "paymentMethod": {
            "card": {
                "number":"4000056655665556",
                "expMonth": 8,
                "expYear": 2026,
                "cvc": "342",
                "name": "John Smith",
                "billingAddress": {
                    "line1": "Bartlett Avenue",
                    "line2": "no. 4",
                    "city": "Southfield",
                    "postalCode": "48076",
                    "state": "Michigan",
                    "country": "USA"
                },
                "isDefault": true
            },
            "bankAccount": {
                "number": "123456",
                "accountHolderName": "John Smith",
                "bankName": "Golden Horizon"
            }
        },
        "externalId": "15793519248",
        "customer": {
            "id": "421dd9b0-0af6-41ee-9fc5-48f42d5ad640",
            "name": "John Smith"
        }
    }
	}
}'
https://api.whenthen.com/api/graphql

Response

ValueType

tokenisePaymentMethod.idID
Unique identifier for the object.
tokenisePaymentMethod.tokenString
value of the token
tokenisePaymentMethod.createdDateDateTime
The date and time at which the token was created yyyy-MM-dd'T'HH:mm:ssZ
tokenisePaymentMethod.customerVaultCustomerApi
Customer details associated to the token

JSON

{
    "data": {
        "tokenisePaymentMethod": {
            "id": "e46d1d90-a71d-45f0-b900-5da4edf67a74",
            "token": "yaGePwkqyBRWaYdA",
            "createdDate": "2022-09-08T11:43:06.085692Z"
        }
    }
}

Get Payment Method

Query

Client TokenPrivate Key

Get payment method.

Request

ValueType

tokenString ﹡
Value of the token or id of payment method

CURL

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "query getPaymentMethod($token: String!){
    getPaymentMethod(token: $token)
  }",
	"variables": {
	    "token": "neHtRZxnhKJsuame"
   }
}'
https://api.whenthen.com/api/graphql

Response

ValueType

getPaymentMethod.idID
Unique identifier for the object.
getPaymentMethod.tokenString
Value of the card token.
getPaymentMethod.numberString
Masked card number.
getPaymentMethod.expMonthInt
Two-digit number representing the card's expiration month.
getPaymentMethod.expYearInt
Two-digit number representing the card's expiration year.
getPaymentMethod.nameString
Cardholder name.
getPaymentMethod.isDefaultBoolean
Is default payment method
getPaymentMethod.brandString
Card brand

JSON

{
    "data": {
        "getPaymentMethod": {
          "id": "e0549aad-b836-4c48-b54a-aebfe573d782",
          "token": "neHtRZxnhKJsuame",
          "number": "**** **** **** 7892",
          "expMonth": 3,
          "expYear": 2030,
          "name": "John Smith",
          "isDefault": false,
          "brand": "VISA",
        }
    }
}

Delete Payment Method

Mutation

Client TokenPrivate Key

Delete a payment method.

Request

ValueType

tokenString ﹡

CURL

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "mutation deletePaymentMethod($token: String!){
    deletePaymentMethod(token: $token)
  }",
	"variables": {
	    "token": "neHtRZxnhKJsuame"
   }
}'
https://api.whenthen.com/api/graphql

Response

ValueType

deletePaymentMethodBoolean
whether the payment method has been successfully deleted

JSON

{
    "data": {
        "deletePaymentMethod": true
    }
}

Create Customer

Mutation

Client TokenPrivate Key

Creates a customer. If payment method data is provided, it also creates a payment method and assigns it to the new customer. The payment method is tokenised and stored in our secure vault.

The Create Customer API enables you to create and manage customers. To setup a card for future payments, you must attach it to a Customer. You can also use the Customer to build card on file solutions.

Request

ValueType

customerVaultCustomerInput ﹡
Customer object
customer.billingAddressBillingAddressInput
The customer’s billing address
customer.descriptionString
An arbitrary string attached to the object
customer.emailString
The customer’s email address
customer.nameString ﹡
The customer’s full name or business name
customer.phoneString
The customer’s phone number
customer.shippingAddressShippingAddressInput
Mailing and shipping address for the customer
customer.companyCompanyInput
Company details for customer
cardPaymentCardInput
Card data for a token we will associate to this customer
card.numberString ﹡
The card number, as a string without any separators
card.expMonthInt ﹡
Two-digit number representing the card’s expiration month
card.expYearInt ﹡
Four-digit number representing the card’s expiration year
card.cvcString
Card security code
card.nameString
Cardholder name
card.billingAddressBillingAddressInput
Cardholder address
card.isDefaultBoolean
Set this as the default payment method

CURL

JAVASCRIPT

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "mutation createCustomer($data: CustomerInput!){
    createCustomer(data: $data)
  }",
	"variables": {
		"data": {
        "card": {
            "number":"4242424242424242",
            "expMonth": 8,
            "expYear": 2026,
            "cvc": "582",
            "name": "John Smith",
            "billingAddress": {
                "line1": "Bartlett Avenue",
                "line2": "no. 4",
                "city": "Southfield",
                "postalCode": "48076",
                "state": "Michigan",
                "country": "USA"
            },
            "isDefault": true
        },
        "customer": {
            "billingAddress": {
                "line1": "Bartlett Avenue",
                "line2": "no. 4",
                "city": "Southfield",
                "postalCode": "48076",
                "state": "Michigan",
                "country": "USA"
            },
            "description": "description",
            "email": "john@example.com",
            "name": "John Smith",
            "phone": "406-694-3629",
            "shippingAddress": {
                "name": "John Smith",
                "phone": "04153 79 44141",
                "address": {
                    "line1": "Gruenauer Strasse 55",
                    "line2": "",
                    "city": "Buchhorst",
                    "postalCode": "16567",
                    "state": "Brandenburg",
                    "country": "DEU"
                }
            }
        }
    }
	}
}'
https://api.whenthen.com/api/graphql

Response

ValueType

createCustomerID
Unique identifier for the customer

JSON

{
    "data": {
        "createCustomer": "9e8daecb-392a-4921-9dbb-384577ac4036"
    }
}

Update Customer

Mutation

Client TokenPrivate Key

Update a customer.

Request

ValueType

idID ﹡
Customer id
customerVaultCustomerInput ﹡
Customer object
customer.billingAddressBillingAddressInput
The customer’s billing address
customer.descriptionString
An arbitrary string attached to the object
customer.emailString
The customer’s email address
customer.nameString ﹡
The customer’s full name or business name
customer.phoneString
The customer’s phone number
customer.shippingAddressShippingAddressInput
Mailing and shipping address for the customer
customer.companyCompanyInput
Company details for customer

CURL

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "mutation updateCustomer($id: ID!,$customer: VaultCustomerInput!){
    updateCustomer(id: $id, customer: $customer)
  }",
	"variables": {
		"id":"9e8daecb-392a-4921-9dbb-384577ac4036",
    "customer": {
        "billingAddress": {
            "line1": "Bartlett Avenue",
            "line2": "no. 4",
            "city": "Southfield",
            "postalCode": "48076",
            "state": "Michigan",
            "country": "USA"
        },
        "description": "description",
        "email": "john@example.com",
        "name": "John Smith",
        "phone": "406-694-3629",
        "shippingAddress": {
            "name": "John Smith",
            "phone": "04153 79 44141",
            "address": {
                "line1": "Gruenauer Strasse 55",
                "line2": "",
                "city": "Buchhorst",
                "postalCode": "16567",
                "state": "Brandenburg",
                "country": "DEU"
            }
        }
    }
	}
}'
https://api.whenthen.com/api/graphql

Response

ValueType

updateCustomerBoolean ﹡
Whether the customer has been successfully updated

JSON

{
    "data": {
        "updateCustomer": true
    }
}

Get Customer

Query

Client TokenPrivate Key

Get customer.

Request

ValueType

idString ﹡
Customer id

CURL

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "query getCustomer($id: String!){ getCustomer(id: $id) }",
	"variables": {
	    "id": "440482b8-9197-4ac1-9f48-2832d9a0c662"
   }
}' https://api.whenthen.com/api/graphql

Response

ValueType

getCustomer.idID
Customer id
getCustomer.billingAddressBillingAddressApi
The customer's address
getCustomer.emailString
An arbitrary string attached to the object
getCustomer.nameString
The customer's full name or business name
getCustomer.shippingAddressShippingAddressApi
Mailing and shipping address for the customer
getCustomer.systemCreatedDateTime
The date and time at which the customer was created yyyy-MM-dd'T'HH:mm:ssZ
getCustomer.systemUpdatedDateTime
The date and time at which the customer was updated yyyy-MM-dd'T'HH:mm:ssZ
getCustomer.defaultPaymentMethodString
Default payment method of the customer

JSON

{
    'data': {
      'getCustomer': {
         'id':'440482b8-9197-4ac1-9f48-2832d9a0c662',
         'name':'John Smith',
         'email':'john.smith@example.com',
         'billingAddress': {
           'line1': "3589 Main Rd.",
           'line2': "West Hill.",
           'city': "Kilcoole",
           'postalCode': "93027",
           'postalCode': "Waterford",
           'postalCode': "IRL"
         }
    }
}

Get Payment Methods

Query

Client TokenPrivate Key

Get payment methods attached to a customer.

Request

ValueType

customerIdString ﹡
Unique identifier for the customer

CURL

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "query getPaymentMethods($customerId: String!){
    getPaymentMethods(customerId: $customerId)
  }",
	"variables": {
	    "customerId": "33acf90a-609f-4b76-8e62-b19e6a1f81bc"
   }
}'
https://api.whenthen.com/api/graphql

Response

ValueType

getPaymentMethods[PaymentMethod]
List of payment methods.
getPaymentMethod.idID
Unique identifier for the object.
getPaymentMethod.tokenString
Value of the card token.
getPaymentMethod.numberString
Masked card number.
getPaymentMethod.expMonthInt
Two-digit number representing the card's expiration month.
getPaymentMethod.expYearInt
Two-digit number representing the card's expiration year.
getPaymentMethod.nameString
Cardholder name.
getPaymentMethod.isDefaultBoolean
Is default payment method
getPaymentMethod.brandString
Card brand

JSON

{
    "data": {
        "getPaymentMethods": [
           {
            "id": "e0549aad-b836-4c48-b54a-aebfe573d782",
            "token": "neHtRZxnhKJsuame",
            "number": "**** **** **** 7892",
            "expMonth": 3,
            "expYear": 2030,
            "name": "John Smith",
            "isDefault": false,
            "brand": "VISA",
           },
           {
            "id": "ec47571f-fcbe-4e62-bd34-5f67fdeae54e",
            "token": "yetVucsiwQsYDdtw",
            "number": "**** **** **** 1584",
            "expMonth": 11,
            "expYear": 2027,
            "name": "John Smith",
            "isDefault": true,
            "brand": "MASTERCARD",
           },
       ]
    }
}

Vault: Update Default Payment Method

Mutation

Client TokenPrivate Key

Set the default payment method for a customer.

Request

ValueType

tokenString ﹡
Value of the token

CURL

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "mutation updateDefaultPaymentMethod($token: String!){
    updateDefaultPaymentMethod(token: $token)
  }",
	"variables": {
	    "token": "neHtRZxnhKJsuame"
   }
}'
https://api.whenthen.com/api/graphql

Response

ValueType

updateDefaultPaymentMethodBoolean
whether the payment method has been successfully updated

JSON

{
    "data": {
        "updateDefaultPaymentMethod": true
    }
}

Headless Request Payment Processor Token

Mutation

Client TokenPrivate Key

Retrieve the payment processor token that is associated with the supplied WhenThenvaultToken.

The associated payment method should have been tokenised in our system before this API is invoked.

It is possible that WhenThen don't currently hold the payment processor token associated with the suppliedvaultToken. In this scenario, WhenThen will need to either tokenise or submit a verification payment against the payment processor in order to retrieve the associated payment processor token. This action may trigger 3DS. For this reason, an accessible callback endpoint should be supplied via the threeDSecureRedirectUrl parameter in the request body. When the 3DS handshake is complete, WhenThen will send the result to the supplied endpoint. If 3DS was successful then this API should be invoked again in order to retrieve the payment processor token from WhenThen's secure vault.

Request

ValueType

tokenRequestHeadlessPaymentProcessorTokenRequest ﹡
A top level object for the individual request fields.
tokenRequest.vaultTokenString ﹡
The WhenThen vault token that represents the payment method
tokenRequest.paymentProcessorConnectionIdString ﹡
The ID of the payment processor connection that was setup in the WhenThen webapp
tokenRequest.currencyCodeString ﹡
The default currency associated with the payment method. ISO 4217 (3 letter alpha code) format.
tokenRequest.threeDSecureRedirectUrlString
This should be supplied when operating in a 3DS-compliant region. The value must be an accessible URL which WhenThen will callback to with a 3DS result. 3DS may be triggered during a call from WhenThen to the payment processor during tokenisation or if a verification payment (zero-value auth) is required.

CURL

JAVASCRIPT

curl
  -X POST
  -H "Content-Type: application/json"
  -H "Authorization: Bearer xxxxxxx"
  -d '{
  	"query": "mutation headlessRequestPaymentProcessorToken($tokenRequest: HeadlessPaymentProcessorTokenRequest!){
      headlessRequestPaymentProcessorToken(tokenRequest: $tokenRequest) {
          token
     }
   }",
  	"variables": {
  		"tokenRequest": {
              "vaultToken": "KbQHOIcQTpOXKmxr",
              "paymentProcessorConnectionId": "connection-provider:ff8705dc-7d94-4a44-abe2-a206d5c833d9",
              "currencyCode": "USD",
              "threeDSecureRedirectUrl": "https://merchant.com/handle-3ds"
          }
  }'
  https://api.whenthen.com/api/graphql

Response

ValueType

headlessRequestPaymentProcessorToken.tokenString
The payment processor token.

JSON

{
    "data": {
        "headlessRequestPaymentProcessorToken": {
            "token": "yaGePwkqyBRWaYdA"
        }
    }
}