Tokens

If you want to keep a customer’s card or bank account on file without holding the sensitive details yourself, store them with the token endpoints. PayChoice holds the details and returns a token you use in later charges instead of the raw card or account data.

Tokens expire after their first use unless they are attached to a customer under Recurring billing. Attach them if you intend to charge more than once.

If you’d rather not touch card or account details at all, the Create Token page captures them on a PayChoice-hosted form and returns the same token.

Store a credit card

curl https://api-sandbox.paychoice.com.au/api/v5/token \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "card[name]": "John Citizen",
    "card[number]": "4111111111111111",
    "card[cvv]": "123",
    "card[expiry_month]": "12",
    "card[expiry_year]": "28"
  }'

curl https://api-sandbox.paychoice.com.au/api/v4/token/ \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -d "card[name]=John Citizen" -d "card[number]=4111111111111111" \
  -d "card[cvv]=123" -d "card[expiry_month]=12" -d "card[expiry_year]=28"

{
  "card": {
    "token": "c629ac3b-682b-41e4-9a81-9445960843cf",
    "card_name": "John Citizen",
    "masked_number": "411111XXXXXX1111",
    "expiry_month": "12",
    "expiry_year": "28",
    "card_type": "Visa",
    "key_id": 1,
    "link": { "href": "/api/v5/token/c629ac3b-682b-41e4-9a81-9445960843cf", "rel": "self" }
  },
  "object_type": "card",
  "merchant_guid": "315564b9-b863-4016-8c53-02c9d8cc80b7",
  "from_item": 0,
  "to_item": 0,
  "total_count": 0
}

Returns HTTP 200 on v4 and 201 Created on v5. merchant_guid sits at the top level, outside card. card_type is one of Visa, MasterCard, AmericanExpress, DinersClub, Jcb, Discover, BankCard or Unknown. Pass card.token as card_token on Create a charge in place of the card[...] fields.

Store a bank account

curl https://api-sandbox.paychoice.com.au/api/v5/bank_token \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "bank[name]": "John Citizen",
    "bank[bsb]": "123123",
    "bank[number]": "123123123"
  }'

{
  "bank": {
    "bank_token": "9acf4194-3651-4414-8415-6b8eb74ece6d",
    "name": "John Citizen",
    "bsb": "123123",
    "number": "XXXXX3123",
    "merchantguid": "315564b9-b863-4016-8c53-02c9d8cc80b7",
    "link": { "href": "/api/v5/bank_token/9acf4194-3651-4414-8415-6b8eb74ece6d", "rel": "self" }
  },
  "object_type": "bank"
}

bank[bsb] is not required for New Zealand accounts; supply the full 15–16 digit account number instead. This response has no paging fields. Pass bank.bank_token as bank_token on a bank charge.

Retrieve and remove

	Card	Bank account
Retrieve	`GET /token/{token}`	`GET /bank_token/{bank_token}`
Remove	`DELETE /token/{token}`	`DELETE /bank_token/{bank_token}`

Retrieve returns the stored details with any empty fields omitted; on the card endpoint expiry_month and expiry_year come back as integers. A token that has been removed returns 410 Gone, which is a reliable way to check whether a token is still usable before charging it.

Payment methods — attach a token to a customer so it doesn’t expire.
Create Token page — capture a token without seeing the details.

Getting started

Taking payments

Getting the result

Storing payment methods

After the payment

Recurring billing

Coming soon

Store a credit card

Store a bank account

Retrieve and remove

Next

​Store a credit card

​Store a bank account

​Retrieve and remove

​Next

Store a credit card

Store a bank account

Retrieve and remove

Next