Network Token OpenAPI Spec
openapi: 3.0.1
info:
title: BR-DGE REST API
description: >
The BR-DGE REST API is designed to provide you with a single integration
into the BR-DGE payment marketplace which unlocks access to a wide
variety of third party payment services such as Payment Service Providers
(PSPs), Digital Wallets, Alternative Payment Methods (APMs), and other
services.
Please see our [Web SDK documentation] for more information about how we can
help you integrate you client applications with us.
## Authorization
API keys can be generated via the BR-DGE portal and are grouped into two main
classes, based on how they will be used:
- Server API Keys for use by your in your secure back-end services, *and must
not be exposed to your end users.*
- Separate Client API Keys will be provided for use in client applications to
support certain features that need to happen in untrusted client environments.
## Environment Sub Domains
The BR-DGE REST API is hosted on two subdomains, <https://sandbox.comcarde.com>
for testing and <https://secure.comcarde.com> for live payments.
**IMPORTANT** In order to ensure [PCI
Compliance](https://www.pcisecuritystandards.org/) please only use mock
payment instrument data when interacting with our Sandbox API.
[Web SDK documentation]: https://docs.br-dge.io/docs/web-sdk-introduction
version: v1
contact:
name: Customer Support
url: https://comcarde.atlassian.net/servicedesk/customer/portals
servers:
- url: https://sandbox.comcarde.com
description:
Sandbox subdomain for testing your integration works as expected, using
mock payment instruments only
- url: https://secure.comcarde.com
description: Use this subdomain for processing live payments.
tags:
- name: Payment Instrument Tokenization
description: Convert payment instruments (cards, Card-on-File) into tokens
- name: Merchant Server
description: Operations intended for use by Merchant servers
- name: Merchant Client Application
description: Operations intended for use by Merchant client applications
externalDocs:
description: Find more info here
url: https://docs.br-dge.io/docs
paths:
/v1/payment-instruments:
post:
tags:
- 'Payment Instrument Tokenization'
- 'Merchant Client Application'
summary: 'Create new Card-on-File'
description: >
Further streamline your checkout experience by securely storing customer
card details in BR-DGE to save them having to re-enter cardholder
details in future.
A Network Token may be asynchronously provisioned if enabled on your
Retail Channel. Merchants can track the status of Network Tokens via
webhook callbacks or by querying the Card-on-Files via
`GET /v1/payment-instruments`.
Please see <https://docs.br-dge.io/docs/vault> for more information.
operationId: 'tokenizeInstrument'
security:
- 'ClientApiKey': []
requestBody:
description: 'Card payment instrument to be tokenized'
content:
application/json:
schema:
$ref: '#/components/schemas/CardholderData'
example:
type: 'card'
nameOnCard: 'John F Doe'
pan: '4444 3333 2222 1111'
expiryDate: '01-99'
required: true
responses:
201:
description: 'Successful tokenization of payment instrument'
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
examples:
full card metadata:
description: If full BIN lookup data is available for the PAN
value:
token: 01ed22f0-5f16-47ba-945f-abfacc59777c
id: c32d62c2-af44-4efb-8452-38c355bfffb5
tokenType: 'CARD'
cardType: 'VISA'
nameOnCard: 'John Doe'
pan: '**** **** **** 1111'
expiryDate: '06-30'
metadata:
cardBrand: 'VISA'
issuer: 'ACMEBANK'
type: 'DEBIT'
category: 'CLASSIC'
countryIsoA2: 'GB'
commercial: true
networkTokenProvisioningStatus: PROVISIONING
fingerprint: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6'
fingerprintExtended: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60630'
no metadata:
description: If only partial BIN lookup data is available for PAN
value:
token: c3710e80-6fc0-4750-8074-6324f7a8be5c
id: c53af59c-b436-4238-b9bc-cc9350b2a2cd
tokenType: 'CARD'
cardType: 'VISA'
nameOnCard: 'John Doe'
pan: '**** **** **** 1111'
expiryDate: '06-30'
networkTokenProvisioningStatus: PROVISIONING
fingerprint: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6'
fingerprintExtended: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60630'
partial card metadata:
description: If only partial BIN lookup data is available for
PAN. Please note that all fields are nullable.
value:
token: 0c608bb2-5b18-497b-a642-c327d088e20f
id: fb095932-2819-4b5d-811f-6adad7cab3cc
tokenType: 'CARD'
cardType: 'VISA'
nameOnCard: 'John Doe'
pan: '**** **** **** 1111'
expiryDate: '06-30'
metadata:
type: 'CLASSIC'
networkTokenProvisioningStatus: PROVISIONING
fingerprint: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6'
fingerprintExtended: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60630'
400:
description:
'Unsuccessful tokenization of payment instrument - bad request'
content:
application/json:
schema:
$ref: '#/components/schemas/ComcardeResponse'
examples:
Bad request with validation errors:
value:
code: 4000
message: Request Error - The request is invalid
id: 4fad8e2e06a15656
validationErrors:
paymentInstrument.pan:
[
4030203 - The value entered for Pan is incorrect. It
is not a valid card PAN.,
]
paymentInstrument.expiryDate:
[4030301 - Expiry Date cannot be blank.]
description: >
This example shows the [4030203] and [4030301] **Validation Errors**.
A full list of possible validation errors are available [here].
[4030203]: https://docs.br-dge.io/docs/validation-errors#4030203
[4030301]: https://docs.br-dge.io/docs/validation-errors#4030301
[here]: https://docs.br-dge.io/docs/validation-errors
500:
$ref: '#/components/responses/UnknownServerError'
callbacks:
Network Token Provisioning Failed Event:
'https://example.com/BR-DGE/ as defined in your retail channel config':
post:
description: An unsuccessful attempt was made to provision a
network token for a BR-DGE Card-on-File.
parameters:
- $ref: '#/components/parameters/callbackValudationHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkTokenProvisioningFailedCallback'
example:
type: token.network.provisioning.failed
merchantAccountId: aadf8010-4df3-49c6-96c0-9f175f60ef36
token: c2fcf424-d7df-4b8b-aa98-3a60ce990d7c
customerId: customer-1234
code: 'TBD'
message: Network Token Provisioning Failed
responses:
'200':
description: Your server returns this code if it accepts the callback
Network Token Status Change Event:
$ref: '#/components/callbacks/NetworkTokenStatusChangeEvent'
Network Token Metadata Update Event:
'https://example.com/BR-DGE/ as defined in your retail channel config':
post:
description: The network token has had metadata updated that
you can access via `GET /v1/payment-instruments`.
parameters:
- $ref: '#/components/parameters/callbackValudationHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkTokenMetadataUpdateCallback'
example:
type: token.network.metadataUpdate
merchantAccountId: aadf8010-4df3-49c6-96c0-9f175f60ef36
token: c2fcf424-d7df-4b8b-aa98-3a60ce990d7c
customerId: customer-1234
network:
token: WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK
status: ACTIVE
issuer: VISA
isCardArtUpdated: true
code: 'TBD'
message: Network Token Metadata Updated
responses:
'200':
description: Your server returns this code if it accepts the
callback
links:
Query Card-on-File and associated Network Token:
operationId: getTokenizedPaymentInstrumentsUsingGET
parameters:
userId: '$response.body#/token'
description: >
The `token` value contained in the callback can be used
as the `token` parameter in
`GET /v1/payment-instruments`.
get:
tags:
- 'Payment Instrument Tokenization'
- 'Merchant Server'
summary:
Retrieve information about Card-on-Files
operationId: getTokenizedPaymentInstrumentsUsingGET
description: >
You can also use this endpoint to query all Card-on-Files for a customer,
if a customer identifier was provided when cards were saved.
Note: If multiple query params are provided, ALL will be used to
constrain the results returned.
security:
- 'ServerApiKey': []
parameters:
- name: customerId
in: query
description: >
Case-sensitive identifier for your customer.
Note: Symbols such as back-ticks and carriage returns are not
permitted.
schema:
type: string
example: 9f3cd197-4363-47e6-8929-9b128a7a8692
- name: tokens
in: query
description: >
Comma-separated list of multi-use tokens.
This is useful if you track associations between your customers and
Card-on-Files yourselves, but still want to access obfuscated card
details on demand
schema:
type: string
examples:
oneId:
summary: Example of querying a single token
value: 72f31b02-d7cf-4050-9026-2ee3d8cc69bb
multipleIds:
summary: Example of querying multiple tokens
value: 72f31b02-d7cf-4050-9026-2ee3d8cc69b,188dccfa-a8bc-4447-a81b-8c39422f9d5a,cc07dec1-144f-4d4d-9204-feec0222c9e4
- name: showPanLeadingChars
in: query
description: >
The leading six digits of a cards PAN are the issuer identification
number (IIN) sometimes referred to as the "bank identification
number (BIN)" which may be required for some use cases.
By default this information is not provided, but you can opt-in by
setting this flag to true if you specifically need it.
E.g. `1234 56** **** 7890` instead of the default `**** **** ****
7890`
schema:
type: boolean
responses:
200:
description: Map of obfuscatedCards, keyed by their multi-use token.
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseMapObfuscatedCard'
examples:
'BR-DGE Card-on-File with pending Network Token provisioning':
description: If enabled on your Retail Channel, a Network Token may be
asynchronously provisioned for your BR-DGE Card-on-File.
value:
id: example-response-trace-id
results:
7e0f5f0c-e720-4deb-ab84-12f8a9f92715:
cardType: MASTERCARD
pan: "####-####-####-4590"
expiryDate: 02-36
startDate: 12-22
metadata:
cardBrand: MASTERCARD
type: CREDIT
countryIsoA2: US
commercial: false
networkTokenProvisioningStatus: PROVISIONING
fingerprint: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd
fingerprintExtended: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd0236
'BR-DGE Card-on-File with active Network Token':
description: If a Card-on-File has an associated active
Network Token then it will be used where possible in
payments. Merchants will also be able to directly provision
Network Token Cryptograms using the Card-on-File token via
`POST /v1/payment-instruments/{token}/network-token-cryptogram`
value:
id: example-response-trace-id
results:
7e0f5f0c-e720-4deb-ab84-12f8a9f92715:
cardType: MASTERCARD
pan: "####-####-####-4590"
expiryDate: 02-36
startDate: 12-22
metadata:
cardBrand: MASTERCARD
type: CREDIT
countryIsoA2: US
commercial: false
networkTokenProvisioningStatus: PROVISIONED
networkToken:
id: WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK
token: '5186151969968300'
expiryDate: '08-26'
issuer: MASTERCARD
status: ACTIVE
tokenUniqueReference: DM4MMC0000000001cd2826c715b7475bb089b7622366ebe4
paymentAccountReference: 5001EUMYTT3AESCZGUEC77KPCLETI
cardArtUri: https://stage.assets.mastercard.com/card-art/combined-image-asset/MyBank-mastercard.png
fingerprint: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd
fingerprintExtended: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd0236
'BR-DGE Card-on-File with disabled Network Token':
description: >
If a Card-on-File has an associated Network Token that has
been flagged as disabled then it will not be possible to
provison Cryptograms for the Network Token until it
re-enters an active state.
value:
id: example-response-trace-id
results:
7e0f5f0c-e720-4deb-ab84-12f8a9f92715:
cardType: MASTERCARD
pan: "####-####-####-4590"
expiryDate: 02-36
startDate: 12-22
metadata:
cardBrand: MASTERCARD
type: CREDIT
countryIsoA2: US
commercial: false
networkTokenProvisioningStatus: PROVISIONED
networkToken:
id: WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK
token: '5186151969968300'
expiryDate: '08-26'
issuer: MASTERCARD
status: DISABLED
tokenUniqueReference: DM4MMC0000000001cd2826c715b7475bb089b7622366ebe4
paymentAccountReference: 5001EUMYTT3AESCZGUEC77KPCLETI
cardArtUri: https://stage.assets.mastercard.com/card-art/combined-image-asset/MyBank-mastercard.png
fingerprint: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd
fingerprintExtended: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd0236
'BR-DGE Card-on-File with unprovisioned Network Token':
description: A BR-DGE Card-on-File may indicate that a
network is unprovisioned if the feature isn't enabled
on the retail channel, or the card network is unsupported.
value:
id: example-response-trace-id
results:
7e0f5f0c-e720-4deb-ab84-12f8a9f92715:
cardType: MASTERCARD
pan: "####-####-####-4590"
expiryDate: 02-36
startDate: 12-22
metadata:
cardBrand: MASTERCARD
type: CREDIT
countryIsoA2: US
commercial: false
networkTokenProvisioningStatus: UNPROVISIONED
fingerprint: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd
fingerprintExtended: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd0236
'BR-DGE Card-on-File with failed Network Token provisioning':
description: If an attempt to provision a Network Token for a
Card-on-File fails then
`results.{Card-on-File-token}.networkTokenProvisioningStatus`
will be set to `FAILED`.
value:
id: example-response-trace-id
results:
7e0f5f0c-e720-4deb-ab84-12f8a9f92715:
cardType: MASTERCARD
pan: "####-####-####-4590"
expiryDate: 02-36
startDate: 12-22
metadata:
cardBrand: MASTERCARD
type: CREDIT
countryIsoA2: US
commercial: false
networkTokenProvisioningStatus: FAILED
fingerprint: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd
fingerprintExtended: badc12faf7f0d63935770a9b8ed07b4cef6dd4d1659ffbc9b41b9a8502dfaefd0236
links:
Provision Network Token Cryptogram:
operationId: postPaymentInstrumentNetworkTokenCryptogram
parameters:
token: '$response.body#/results/{card-on-file-token}'
description: >
If `results.{card-on-file-token}.networkToken.status` is
`ACTIVE` then the `results.{card-on-file-token}` value can be
used as the `token` parameter in
`POST /v1/payment-instruments/{token}/network-token-cryptogram`.
400:
description: >
Bad request - the request was in an invalid format or contained
invalid information.
If have any questions about why you are receiving these responses,
please raise a ticket with support on the BR-DGE Support Portal at
<https://comcarde.atlassian.net/servicedesk/customer/portals>
with the `id` from the response so we track down the individual requests on our end.
content:
application/json:
schema:
$ref: '#/components/schemas/ComcardeResponse'
examples:
Invalid customer ID:
value:
code: 4000
message:
getTokenizedPaymentInstruments.customerId contains invalid
characters
Querying by tokens and customer ID:
value:
code: 4000
message:
Querying with both tokens and customerId is not currently
supported
401:
$ref: '#/components/responses/UnauthorizedRequest'
500:
$ref: '#/components/responses/UnknownServerError'
/v1/payment-instruments/{token}:
delete:
tags:
- 'Payment Instrument Tokenization'
- 'Merchant Client Application'
- 'Merchant Server'
summary: 'Delete a Card-on-File'
operationId: 'deleteTokenizeInstrument'
description: Please note that any associated Network Tokens will also be
deleted.
security:
- 'ClientApiKey': []
- 'ServerApiKey': []
parameters:
- $ref: '#/components/parameters/pathToken'
responses:
400:
description: 'Unsuccessful deletion of Card-on-File - bad request'
404:
description: 'Card-on-File not found'
content:
application/json:
schema:
$ref: '#/components/schemas/ComcardeResponse'
example:
code: 4000
message: 'Invalid request'
id: 4fad8e2e06a15656
500:
$ref: '#/components/responses/UnknownServerError'
200:
description: 'Successful deletion of Card-on-File'
callbacks:
Network Token Status Change Event:
$ref: '#/components/callbacks/NetworkTokenStatusChangeEvent'
/v1/payment-instruments/{token}/network-token-cryptogram:
post:
tags:
- 'Payment Instrument Tokenization'
- 'Merchant Server'
summary: Creates a cryptogram for a Card-on-File.
operationId: postPaymentInstrumentNetworkTokenCryptogram
security:
- 'ServerApiKey': []
parameters:
- $ref: '#/components/parameters/pathToken'
responses:
201:
description: Cryptogram created.
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkTokenCryptogram'
400:
description: Unable to provision Cryptogram - Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ComcardeResponse'
examples:
Unprovisioned Network Token:
value:
code: TBD
message: Card-on-File does not have an associated Network
Token.
id: 4fad8e2e06a15656
description: This may be due to the feature not being enabled
on your Retail Channel, or because the card is from an
unsupported scheme.
Pending Network Token Provisioning:
value:
code: TBD
message: Network Token provisioning in progress. Please try
again later.
id: 4fad8e2e06a15656
description: A Card-on-File needs to have a provisioned and
active Network Token in order to provision a Cryptogram.
Card-on-File has a disabled Network Token:
value:
code: TBD
message: Associated Network Token is disabled.
id: 4fad8e2e06a15656
description: A Card-on-File needs to have an active Network
Token in order to provision a Cryptogram.
Network Token Provisioning Failed:
value:
code: TBD
message: Provisioning of Network Token for this
Card-on-File failed.
id: 4fad8e2e06a15656
401:
description: Unauthorized request.
404:
description: The specified payment instrument was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ComcardeResponse'
examples:
entity-not-found:
$ref: '#/components/examples/entity-not-found'
500:
description:
Unsuccessful creation of network token cryptogram - an internal server error occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ComcardeResponse'
examples:
Internal server error:
value:
code: 5001
message: Server Error - An unexpected error occurred when processing the request
id: 4fad8e2e06a15656
description: |
This example shows the [5001 error code].
A full list of possible response codes is available [here].
[5001 error code]: https://secure.comcarde.com/docs/rest-api/response-codes#5001
[here]: https://secure.comcarde.com/docs/rest-api/response-codes
components:
schemas:
ComcardeResponse:
title: ComcardeResponse
type: object
properties:
additionalErrorDetails:
type: string
description: >-
Additional information that may sometimes be returned about the reason an error occurred.
code:
type: string
description: >-
[Response Code](https://secure.comcarde.com/docs/rest-api/response-codes)
signifying the outcome of the request.
example: '1000'
id:
type: string
description: >
The ID of this request. If you can include these when querying the
outcome of individual requests, we can track down the root cause
faster.
example: a7f45953-1e8b-4f33-87b0-3293f4f6972f
message:
type: string
description: A description of the outcome of the request.
validationErrors:
type: object
additionalProperties:
type: string
description: An object that contains validation errors
Card:
title: Card
description: >
A type of [Payment Instrument] representing a credit or debit payment
card.
[Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument
type: object
required:
- expiryDate
- pan
- type
properties:
type:
type: string
description: Discriminator field. Please see the discriminator
mapping for the `PaymentInstrument` schema.
nameOnCard:
maxLength: 45
minLength: 2
pattern: ^([A-Z 0-9 a-z-'.]*)$
type: string
description: |-
Name on the credit or debit card
Please use only letters, numbers, spaces and these symbols: -'.
example: John F Doe
pan:
type: string
description: PAN of the credit or debit card.
example: 4444 3333 2222 1111
expiryDate:
type: string
description: Expiry date of the credit or debit card.
example: 01-99
startDate:
type: string
description: Start date of the credit or debit card.
example: 01-00
issueNumber:
maximum: 9
minimum: 1
type: integer
description: Issue number of the credit or debit card.
format: int32
example: 1
cv2:
pattern: ^[0-9]*$
type: string
description: |-
CV2 of the credit or debit card
Please use only numbers
example: '123'
tokenize:
type: boolean
description: If true, then a Card-on-File will be created.
example: false
ComcardeCode:
title: ComcardeCode
type: object
properties:
code:
type: string
example: 1000
description: A unique identifier covering the outcome of the request.
description:
type: string
description: A description of the outcome of the request.
ObfuscatedCard:
description: >
Information about card payment instruments. This can be used to help
cardholders identify which of their cars were used (without becoming PCI
sensitive) in addition to the metadata providing useful insights for
merchants.
type: object
properties:
tokenType:
type: string
example: 'CARD'
description: 'Always `CARD`'
enum: ['CARD']
cardType:
type: string
description: >
Please use `metadata`.`cardBrand` instead.
This field is now deprecated and will be removed in a future update.
example: VISA
deprecated: true
nameOnCard:
type: string
description: Name on the credit or debit card.
example: John F Doe
pan:
type: string
description: PAN of the credit or debit card in obfuscated form.
example: '**** **** **** 1111'
expiryDate:
type: string
description: Expiry date of the credit or debit card.
example: 06-30
startDate:
type: string
description: Start date of the credit or debit card.
example: 01-20
issueNumber:
type: integer
description: Issue number of the credit or debit card.
format: int32
customerId:
type: string
description: >
ID of the merchant's customer who owns the payment instrument (if
available)
example: example-customer-id
pspTokens:
type: array
description: a set of psp tokens linked to this Card-on-File
items:
type: object
description: PSP Token linked to this Card-on-File
properties:
pspName:
$ref: '#/components/schemas/PspNames'
description: Identifier for the Payment Service Provider (PSP)
associated with the token.
token:
type: string
description: the token generate by the psp
pspCardFingerprint:
type: string
description: The PSP fingerprint for the payment instrument (if available)
fingerprint:
type: string
description: >
A unique token that can be used to detect if two BR-DGE tokens represent
the same underlying Payment Instrument.
example: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6'
fingerprintExtended:
type: string
description: >
A fingerprint with card expiry date appended in MMYY format.
cardArtUri:
type: string
description: URI to card art
format: uri
example: https://example.com/card-art/09a29968-f53f-4bdb-9744-6033996ee55f
metadata:
$ref: '#/components/schemas/CardMetadata'
networkTokenProvisioningStatus:
$ref: '#/components/schemas/NetworkTokenProvisioningStatus'
networkToken:
$ref: '#/components/schemas/NetworkToken'
NetworkToken:
type: object
description: >
Information about a Network Token.
properties:
id:
type: string
description: A unique identifier that represents the token associated
with a card enrolled into the Card Network Service
example: WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK
token:
type: string
description: The unique token for the enrolled PAN which can be used
in authorization as per ISO/IEC 7812 format.
example: 5186151969968300
expiryDate:
type: string
description: Expiration date of the token, noted in MM-YY Format
example: 08-26
issuer:
type: string
enum:
- MASTERCARD
- VISA
description: The issuing card network of the network token
example: MASTERCARD
status:
$ref: '#/components/schemas/NetworkTokenStatus'
tokenUniqueReference:
type: string
description: Unique identifier for the network token provided by the
Card Network
example: DM4MMC0000000001cd2826c715b7475bb089b7622366ebe4
paymentAccountReference:
type: string
description: >
A non-financial reference assigned to each unique funding PAN (FPAN)
that's used to link the payment account of that PAN to affiliated
payment tokens.
example: 5001EUMYTT3AESCZGUEC77KPCLETI
NetworkTokenStatus:
type: string
description: >
The status of the network token.
- `ACTIVE`: Can be used to provision Cryptograms for payments.
- `DISABLED`: This can be due to card suspensions, fraud, or other
temporary hold reasons and may be re-activated at a later date.
- `DELETED`: The token is no longer valid and cannot be re-activated.
This can be due to token expirations, lost card or other
non-temporary reasons.
enum:
- ACTIVE
- DISABLED
- DELETED
example: ACTIVE
NetworkTokenProvisioningStatus:
type: string
description: |
The status of the network token provisioning. It can be one of the following states:
- `UNPROVISIONED`: A network token has not attempted to be provisioned, is not enabled or not valid for this payment instrument.
- `PROVISIONING`: Provisioning has been triggered but is not completed.
- `FAILED`: Provisioning has failed. The provisioning could not be completed.
- `PROVISIONED`: Provisioning was successful, and a network token is available for use.
enum:
- UNPROVISIONED
- PROVISIONING
- FAILED
- PROVISIONED
example: PROVISIONED
NetworkTokenCryptogram:
type: object
required:
- cryptogram
- eci
properties:
cryptogram:
description: The cryptogram value.
type: string
example: Qwertyuio0987654321asdfghjklpois
eci:
description: The electronic commerce indicator (ECI).
type: string
example: 07
ResponseMapObfuscatedCard:
title: ResponseMapObfuscatedCard
type: object
description: Map of Card-on-Files, keyed by their multi-use token.
properties:
id:
type: string
description: >
The ID of this request. If you can include these when querying the
outcome of individual requests, we can track down the root cause
faster.
results:
type: object
description: Map of obfuscated cards keyed by multi-use token
additionalProperties:
$ref: '#/components/schemas/ObfuscatedCard'
example:
id: example-response-trace-id
results:
3d967f3e-8710-4c2b-9828-28b9531617f1:
cardType: VISA
nameOnCard: John F Doe
pan: '**** **** **** 1111'
expiryDate: 06-30
startDate: 01-20
issueNumber: 0
customerId: example-customer-id
tokenType: 'CARD'
metadata:
cardBrand: 'VISA'
issuer: 'ACMEBANK'
type: 'DEBIT'
category: 'CLASSIC'
countryIsoA2: 'GB'
commercial: true
fingerprint: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6'
fingerprintExtended: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60630'
example-token-2:
cardType: MASTERCARD
nameOnCard: Jane Doe
pan: '**** **** **** 1234'
expiryDate: 07-31
startDate: 09-21
issueNumber: 2
customerId: example-customer-id
tokenType: 'CARD'
metadata: null
fingerprint: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6'
fingerprintExtended: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60731'
4c5f1e1d-a8d4-403c-8199-e9705da98735:
cardType: MASTERCARD
nameOnCard: John F Doe
pan: '**** **** **** 4321'
expiryDate: 02-29
startDate: 10-20
customerId: example-customer-id
tokenType: 'CARD'
metadata:
cardBrand: 'MASTERCARD'
issuer: null
type: 'DEBIT'
category: null
countryIsoA2: 'GB'
commercial: null
fingerprint: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6'
fingerprintExtended: '63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60229'
TokenResponse:
description: >
A single-use token representing a card payment instrument along with
information about the card.
allOf:
- type: object
properties:
id:
type: string
description: >
The ID of this request. If you can include these when querying
the outcome of individual requests, we can track down the root
cause faster.
token:
type: string
description: Single-use token
- $ref: '#/components/schemas/ObfuscatedCard'
CardMetadata:
type: object
description: >
If a card payment instrument is used then BR-DGE may be able to provide
metadata about the card
**Please note: All text will be UPPERCASE and all fields can be null**
properties:
cardBrand:
type: string
example: 'MASTERCARD'
description: 'MASTERCARD, VISA, etc'
nullable: true
issuer:
type: string
description: 'Name of issuing bank'
nullable: true
type:
type: string
enum:
- DEBIT
- CREDIT
- CHARGE_CARD
nullable: true
category:
type: string
example: 'CLASSIC'
description: 'CLASSIC, BUSINESS, MIXED_PRODUCT, etc'
nullable: true
countryIsoA2:
type: string
description: 'ISO 3166 Alpha-2 Country code'
example: 'GB'
nullable: true
commercial:
type: boolean
description: 'Indicates if the card is corporate or retail'
example: true
nullable: true
CardholderData:
required:
- 'expiryDate'
- 'pan'
- 'type'
type: 'object'
description: 'Payment instrument that is a credit or debit card.'
properties:
type:
type: string
example: 'card'
enum:
- 'card'
description: 'Must be set to card'
customerId:
maxLength: 100
minLength: 1
pattern: "^([\\p{L}\\p{M} 0-9'\\[\\]()@?!\\-/.,_&*:;+=`]*)$"
type: string
description: Identifier for the merchant's customer who owns the
payment instrument to be tokenized.
nameOnCard:
maxLength: 255
minLength: 1
pattern: "^([\\p{L}\\p{M} 0-9'\\[\\]()@?!\\-/.,_&*:;+=`]*)$"
type: string
description:
'Name on the credit or debit card. This may be required by the
payment services provider (PSP).'
example: 'John F Doe'
pan:
type: string
description: 'PAN of the credit or debit card.'
example: '4444 3333 2222 1111'
expiryDate:
type: string
description: 'Expiry date of the credit or debit card.'
example: '01-99'
startDate:
type: string
description: 'Start date of the credit or debit card.'
example: '01-00'
issueNumber:
maximum: 9
minimum: 1
type: 'integer'
description: 'Issue number of the credit or debit card.'
format: 'int32'
example: 1
CardholderDataWithOptionalCvv:
type: object
allOf:
- $ref: '#/components/schemas/CardholderData'
- type: object
properties:
cv2:
pattern: '[0-9]*$'
type: string
description: 'CV2 of the credit or debit card.'
example: '123'
TokenizedCardholderData:
required:
- 'token'
- 'type'
type: object
description:
Payment instrument consisting of a token that is a tokenized version of
another payment instrument
properties:
type:
type: string
description: 'Must be set to tokenized'
example: 'tokenized'
enum:
- 'tokenized'
token:
maxLength: 200
minLength: 1
pattern: "^([\\p{L}\\p{M} 0-9'\\[\\]()@?!\\-/.,_&*:;+=`]*)$"
type: string
description: The token that represents a payment instrument.
example: 00000000-0000-0000-0000-000000000000
cv2:
maxLength: 4
minLength: 3
pattern: '[0-9]*$'
type: string
description: CV2 of the Tokenized payment instrument.
example: '000'
PspNames:
type: string
description: Names of Payment Service Providers
example: Checkout.com
enum:
- Barclaycard ePDQ - Smartpay Checkout
- Braintree
- Barclaycard Smartpay Fuse
- Checkout.com
- Cybersource
- Nuvei
- PayPal-Direct
- Stripe
- Trust Payments
- Worldline Online Payments
BaseCallback:
type: object
required:
- type
- merchantAccountId
- code
- message
properties:
type:
type: string
merchantAccountId:
type: string
description: >
Identifier of the merchant account associated with the payment
example: 00000000-0000-0000-0000-000000000000
code:
type: string
description: >-
[Response Code](https://docs.br-dge.io/docs/response-codes)
signifying the outcome of the request
example: '1000'
message:
type: string
description: A description of the outcome
TokenCallback:
allOf:
- $ref: '#/components/schemas/BaseCallback'
- type: object
required:
- token
properties:
token:
type: string
description: The token for the associated BR-DGE Card-on-File.
customerId:
type: string
description: The ID of the customer the token is attached to.
NetworkTokenProvisionedCallback:
allOf:
- $ref: '#/components/schemas/TokenCallback'
- type: object
required:
- network
properties:
network:
type: object
required:
- token
- status
- issuer
properties:
token:
type: string
status:
$ref: '#/components/schemas/NetworkTokenStatus'
issuer:
$ref: '#/components/schemas/NetworkTokenIssuer'
NetworkTokenStatusChangeCallback:
allOf:
- $ref: '#/components/schemas/NetworkTokenProvisionedCallback'
NetworkTokenMetadataUpdateCallback:
allOf:
- $ref: '#/components/schemas/NetworkTokenProvisionedCallback'
- type: object
required:
- isCardArtUpdated
properties:
network:
type: object
properties:
isCardArtUpdated:
type: boolean
NetworkTokenProvisioningFailedCallback:
allOf:
- $ref: '#/components/schemas/TokenCallback'
NetworkTokenIssuer:
type: string
enum:
- MASTERCARD
- VISA
description: The issuing card network of the network token
example: MASTERCARD
securitySchemes:
'ServerApiKey':
type: http
scheme: bearer
description: >
**IMPORTANT** This key allows you to perform sensitive operations such
as authorizing payments and refunds.
**Production Server API keys must not be accessible outside your organization.**
'ClientApiKey':
type: http
scheme: bearer
description: >
Separate Client API Keys will be provided for use in client
applications to support certain features that need to happen
in untrusted client environments.
Client API keys provide restricted permissions to ensure they cannot be
misused.
responses:
UnknownServerError:
description: >
An internal server error occurred upstream while processing the request.
If you have any questions about why you are receiving these responses,
please raise a ticket with support on the BR-DGE Support Portal at
<https://comcarde.atlassian.net/servicedesk/customer/portals>
with the `id` from the response so we track down the individual
requests on our end.
content:
application/json:
schema:
$ref: '#/components/schemas/ComcardeResponse'
examples:
Internal server error:
description: |
This example shows the [5001 error code]
A full list of possible response codes is available [here].
[5001 error code]: https://secure.comcarde.com/docs/rest-api/response-codes#5001
[here]: https://secure.comcarde.com/docs/rest-api/response-codes
value:
code: 5001
message: Server Error - An unexpected error occurred when processing the request
id: 4fad8e2e06a15656
UnauthorizedRequest:
description: Unauthorized request.
examples:
entity-not-found:
summary: Entity Not Found Error
description: >
This example shows the [4040 error code].
This occurs when an entity was not found for a given ID, the entity should be clear from context.
A full list of possible response codes is available [here].
[4040 error code]: https://secure.comcarde.com/docs/rest-api/response-codes#4040
[here]: https://secure.comcarde.com/docs/rest-api/response-codes
value:
code: 4040
message: Entity not found
id: 4fad8e2e06a15656
parameters:
pathToken:
name: token
in: path
description: Multi-use token associated with the Card-on-File to be deleted.
required: true
schema:
type: 'string'
callbackValudationHeader:
name: X-Brdge-Validation
in: header
description: Merchants can validate the authenticity of callbacks
by generating a hash from the body along with a shared secret.
schema:
type: string
example: 90c3b3881074021383c8679f0232580f7b96cebacab77517fc4b479e6d977b06
required: true
callbacks:
NetworkTokenStatusChangeEvent:
'https://example.com/BR-DGE/ as defined in your retail channel config':
post:
parameters:
- $ref: '#/components/parameters/callbackValudationHeader'
requestBody:
description: The network token has had metadata updated that you
can access via `GET /v1/payment-instruments`.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkTokenStatusChangeCallback'
examples:
active-network-torken:
summary: Network Token entered an active state
description: You can provision cryptograms for active
Network Token via
`POST /v1/payment-instruments/{token}/network-token-cryptogram`
value:
type: token.network.statusChange
merchantAccountId: aadf8010-4df3-49c6-96c0-9f175f60ef36
token: c2fcf424-d7df-4b8b-aa98-3a60ce990d7c
customerId: customer-1234
network:
token: WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK
status: ACTIVE
issuer: VISA
code: 'TBD'
message: Network Token Status Change
disabled-network-token:
summary: Network Token entered a disabled state
description: The Network Token has been temporarily
disabled. It won't be possible to provision
cryptograms until it moves back into an active state.
value:
type: token.network.statusChange
merchantAccountId: aadf8010-4df3-49c6-96c0-9f175f60ef36
token: c2fcf424-d7df-4b8b-aa98-3a60ce990d7c
customerId: customer-1234
network:
token: WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK
status: DISABLED
issuer: MASTERCARD
code: 'TBD'
message: Network Token Status Change
deleted-network-token:
summary: Network Token deleted
description: The Network Token and associated BR-DGE
Card-on-File has been permanently deleted.
value:
type: token.network.statusChange
merchantAccountId: aadf8010-4df3-49c6-96c0-9f175f60ef36
token: c2fcf424-d7df-4b8b-aa98-3a60ce990d7c
customerId: customer-1234
network:
token: WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK
status: DELETED
issuer: VISA
code: 'TBD'
message: Network Token Status Change
responses:
'200':
description: Your server returns this code if it accepts the callback
links:
Provision Network Token using Card-on-File Token: # <---- arbitrary name for the link
operationId: postPaymentInstrumentNetworkTokenCryptogram
# or
# operationRef: '#/paths/~1users~1{userId}/get'
parameters:
userId: '$response.body#/token'
description: >
If `network.state` is `ACTIVE` then the `token` value
contained in the callback can be used as the `token`
parameter in
`POST /v1/payment-instruments/{token}/network-token-cryptogram`.
Updated 21 days ago