Payment Tokens

Payment tokens are used to reduce the scope of PCI DSS compliance. A payment token can be made using a different authentication scheme (refer to the public key authentication scheme in the Authentication section), which allows you to create a payment token directly from the browser, bypassing the need to send sensitive cardholder info to your servers. We recommend using this with our Rebilly.js library, which helps you wire a form into this API resource and create payment tokens.

Create a payment token

FramePay is the recommended way to create a payment token because it minimizes PCI DSS compliance. Once a payment token is created, it can only be used once.

A payment token expires upon first use or within 30 minutes of the token creation (whichever comes first).

Authorizations:
PublishableApiKeySecretApiKeyJWT
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Request Body schema: application/json

PaymentToken resource.

One of
method
required
string
Value: "payment-card"

The token payment method.

required
object

The payment card instrument details.

object

The billing address object.

object

Risk metadata used for 3DS and risk scoring.

object

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Response Schema: application/json
One of
method
required
string
Value: "payment-card"

The token payment method.

required
object

The payment card instrument details.

object

The billing address object.

id
string <= 50 characters

The token identifier string.

isUsed
boolean
Default: false

Whether the token was already used.

object

Risk metadata used for 3DS and risk scoring.

createdTime
string <date-time>

Token created time.

updatedTime
string <date-time>

Token updated time.

usageTime
string <date-time>

Token usage time.

expirationTime
string <date-time>

Token expiration time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
Example
Payment Card Token
Payment Card Token
Bank Account Token.
Digital Wallet Token
Plaid Account Token
Khelocard card token
Alternative payment token.
{
  • "method": "payment-card",
  • "paymentInstrument": {
    },
  • "billingAddress": {
    },
  • "riskMetadata": {
    },
  • "leadSource": {
    }
}

Response samples

Content type
application/json
Example
Payment Card Token
Payment Card Token
Bank Account Token.
Digital Wallet Token
Plaid Account Token
Khelocard card token
Alternative payment token.
{
  • "method": "payment-card",
  • "paymentInstrument": {
    },
  • "billingAddress": {
    },
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "isUsed": false,
  • "riskMetadata": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "usageTime": "2019-08-24T14:15:22Z",
  • "expirationTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Retrieve a list of tokens

Retrieve a list of tokens.

Authorizations:
SecretApiKeyJWT
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array ()
One of
method
required
string
Value: "payment-card"

The token payment method.

required
object

The payment card instrument details.

object

The billing address object.

id
string <= 50 characters

The token identifier string.

isUsed
boolean
Default: false

Whether the token was already used.

object

Risk metadata used for 3DS and risk scoring.

createdTime
string <date-time>

Token created time.

updatedTime
string <date-time>

Token updated time.

usageTime
string <date-time>

Token usage time.

expirationTime
string <date-time>

Token expiration time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples 

$paymentCardTokens = $client->paymentCardTokens()->search([
    'filter' => 'token:string',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a token

Retrieve a token with specified identifier string.

Authorizations:
PublishableApiKey
path Parameters
token
required
string

The token identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Response Schema: application/json
One of
method
required
string
Value: "payment-card"

The token payment method.

required
object

The payment card instrument details.

object

The billing address object.

id
string <= 50 characters

The token identifier string.

isUsed
boolean
Default: false

Whether the token was already used.

object

Risk metadata used for 3DS and risk scoring.

createdTime
string <date-time>

Token created time.

updatedTime
string <date-time>

Token updated time.

usageTime
string <date-time>

Token usage time.

expirationTime
string <date-time>

Token expiration time.

Array of objects (SelfLink) non-empty

The links related to resource.

Request samples 

$paymentCardToken = $client->paymentCardTokens()->load('tokenId');

Response samples

Content type
application/json
Example
Payment Card Token
Payment Card Token
Bank Account Token.
Digital Wallet Token
Plaid Account Token
Khelocard card token
Alternative payment token.
{
  • "method": "payment-card",
  • "paymentInstrument": {
    },
  • "billingAddress": {
    },
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "isUsed": false,
  • "riskMetadata": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "usageTime": "2019-08-24T14:15:22Z",
  • "expirationTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Validate a digital wallet session

FramePay is the recommended way to use when validating a digital wallet session.

Authorizations:
PublishableApiKeySecretApiKeyJWT
Request Body schema: application/json

Digital wallet validation request.

type
required
string

Type of the digital wallet to validate.

Apple Pay
Apple Pay
required
object

The validation request.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

Response Schema: application/json
type
required
string

Type of the digital wallet to validate.

Apple Pay
Apple Pay
validationResponse
object

The validation response to use by the Apple Pay SDK to proceed.

Request samples

Content type
application/json
{
  • "type": "Apple Pay",
  • "validationRequest": {
    }
}

Response samples

Content type
application/json
{
  • "type": "Apple Pay",
  • "validationResponse": { }
}
Next to Payment Cards