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).

Request
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

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

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

PaymentToken resource.

One of:
method
required
string

The token payment method.

Value: "payment-card"
required
object

The payment card instrument details.

object

The billing address object.

object

Risk metadata used for 3DS and risk scoring.

object
Responses
201Token was created.
Response Schema: application/json
One of:
method
required
string

The token payment method.

Value: "payment-card"
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 (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid data was sent.
post/tokens
Request samples
application/json
{
  • "method": "payment-card",
  • "paymentInstrument": {
    },
  • "billingAddress": {
    },
  • "riskMetadata": {
    },
  • "leadSource": {
    }
}
Response samples
application/json
{
  • "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.

Request
Security:
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

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

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A list of tokens was retrieved successfully.
Response Headers
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

The token payment method.

Value: "payment-card"
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 (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/tokens
Request samples
$paymentCardTokens = $client->paymentCardTokens()->search([
    'filter' => 'token:string',
]);
Response samples
application/json
[
  • {
    }
]

Retrieve a token

Retrieve a token with specified identifier string.

Request
path Parameters
token
required
string

The token identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

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

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200Token was retrieved successfully.
Response Schema: application/json
One of:
method
required
string

The token payment method.

Value: "payment-card"
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 (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
get/tokens/{token}
Request samples
$paymentCardToken = $client->paymentCardTokens()->load('tokenId');
Response samples
application/json
{
  • "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.

Request
Request Body schema: application/json

Digital wallet validation request.

type
required
string

Type of the digital wallet to validate.

required
object

The validation request.

Responses
201Digital wallet validation was made.
Response Schema: application/json
type
required
string

Type of the digital wallet to validate.

validationResponse
object

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

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid data was sent.
post/digital-wallets/validation
Request samples
application/json
{
  • "type": "Apple Pay",
  • "validationRequest": {
    }
}
Response samples
application/json
{
  • "type": "Apple Pay",
  • "validationResponse": { }
}