OpenAPI Specification
openapi: 3.0.3
info:
description: '<h2>Let''s build something great.</h2><p>Welcome to the official reference documentation for Synctera APIs. Our APIs are the best way to automate your company''s banking needs and are designed to be easy to understand and implement.</p><p>We''re continuously growing this library and what you see here is just the start, but if you need something specific or have a question, <a class=''text-blue-600'' href=''https://synctera.com/contact'' target=''_blank'' rel=''noreferrer''>contact us</a>.</p>
'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
title: Synctera Accounts Cards API
version: 0.20.0
servers:
- description: Production
url: https://api.synctera.com/v0
- description: Sandbox (no real world financial impact)
url: https://api-sandbox.synctera.com/v0
security:
- bearerAuth: []
tags:
- description: Requests to issue and manage cards
name: Cards
paths:
/cards:
description: 'The Card object represents your customer''s spending card.
'
summary: Cards
get:
description: 'List of cards matching query parameters
'
operationId: listCards
parameters:
- $ref: '#/components/parameters/customer_id_query'
- $ref: '#/components/parameters/account_id_query_array'
- $ref: '#/components/parameters/emboss_name_query'
- $ref: '#/components/parameters/last_four_query'
- $ref: '#/components/parameters/expiration_date_query'
- $ref: '#/components/parameters/card_type_query'
- $ref: '#/components/parameters/card_brand_query'
- $ref: '#/components/parameters/form_query'
- $ref: '#/components/parameters/card_product_id_query'
- $ref: '#/components/parameters/card_status_query'
- $ref: '#/components/parameters/postal_code_query'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/card_sort_by_query'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/card_list_response'
description: Cards
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: List Cards
tags:
- Cards
x-external: true
post:
description: 'Issue or reissue a new card for a customer
'
operationId: issueCard
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/card_issuance_request'
description: Card to issue
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/card_response'
description: Card issued
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Issue a Card
tags:
- Cards
x-external: true
/cards/{card_id}:
description: 'The Card object represents your customer''s spending card.
'
summary: Cards
get:
description: 'Get the details about a card that has been issued
'
operationId: getCard
parameters:
- $ref: '#/components/parameters/card_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_response'
description: Card details
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Get Card
tags:
- Cards
x-external: true
patch:
description: 'Integrators can update the card resource to change status, update shipping (if the card hasn''t been shipped) or edit metadata.
'
operationId: updateCard
parameters:
- $ref: '#/components/parameters/card_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/card_edit_request'
description: Card edits
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_response'
description: Card issued
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Update Card
tags:
- Cards
x-external: true
/cards/{card_id}/barcodes:
summary: Cards
get:
description: 'This endpoint is for testing environment only to provide access to barcode of a test card
'
operationId: getCardBarcode
parameters:
- $ref: '#/components/parameters/card_id'
responses:
'200':
content:
application/json:
schema:
properties:
barcode:
description: Barcode of the card
type: string
type: object
description: Barcode
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Get Card Barcode
tags:
- Cards
x-external: true
/cards/{card_id}/changes:
get:
description: 'List card change history
'
operationId: listChanges
parameters:
- $ref: '#/components/parameters/card_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_changes_list'
description: List of card changes
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: List Card Changes
tags:
- Cards
x-external: true
/cards/{card_id}/client_token:
description: 'Client access token for accessing privileged details about a card
'
summary: Get Client Access Token
post:
description: 'Create a client access token for interacting with a card. This token will be used on the client to identify the card for flows like viewing Full PAN or setting the PIN in a PCI compliant manner.
'
operationId: getClientAccessToken
parameters:
- $ref: '#/components/parameters/card_id'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/client_token'
description: Client token
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Get a client token
tags:
- Cards
x-external: true
/cards/activate:
description: 'Activate a card
'
summary: Card Activation
post:
description: 'Activate a card
'
operationId: activateCard
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/card_activation_request'
description: Card activation code
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_response'
description: Card activated successfully
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Activate a card
tags:
- Cards
x-external: true
/cards/card_widget_url:
summary: Get Card Widget URL
get:
description: 'This endpoint returns a URL address of the specified widget for a given card
'
operationId: getCardWidgetURL
parameters:
- description: The type of widget for which to construct the URL
in: query
name: widget_type
required: true
schema:
$ref: '#/components/schemas/widget_type'
x-external: true
- in: query
name: customer_id
required: true
schema:
$ref: '#/components/schemas/customer_id1'
x-external: true
- in: query
name: account_id
required: true
schema:
$ref: '#/components/schemas/account_id'
x-external: true
- description: The ID of the card (required for set PIN widget)
in: query
name: card_id
schema:
$ref: '#/components/schemas/card_id'
x-external: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_widget_url_response'
description: Card issued
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Error
summary: Get card widget URL
tags:
- Cards
x-external: true
/cards/gateways:
description: 'The Gateway object represents the Authorization gateway configuration.
'
summary: Authorization Gateway Configuration
get:
description: 'List of gateways matching query parameters
'
operationId: listGateways
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/gateway_list_response'
description: Gateways
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: List Gateways
tags:
- Cards
x-external: true
post:
description: 'Create a new Authorization Gateway Configuration
'
operationId: createGateway
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_gateway_request'
description: Create a new Authorization Gateway Configuration
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/gateway_response'
description: New Authorization Gateway Configuration created
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Create Gateway
tags:
- Cards
x-external: true
/cards/gateways/{gateway_id}:
description: 'The Gateway object represents the Authorization gateway configuration.
'
summary: Authorization Gateway
get:
description: 'Get the details of an Authorization Gateway that has been configured
'
operationId: getGateway
parameters:
- $ref: '#/components/parameters/gateway_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gateway_response'
description: Gateway details
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Get Gateway
tags:
- Cards
x-external: true
patch:
description: 'Update Authorization Gateway configuration
'
operationId: updateGateway
parameters:
- $ref: '#/components/parameters/gateway_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update_gateway_request'
description: Gateway edits
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gateway_response'
description: Gateway Updated
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Update Gateway
tags:
- Cards
x-external: true
/cards/images:
get:
description: 'List all card image details
'
operationId: listCardImageDetails
parameters:
- $ref: '#/components/parameters/customer_id_query_required'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_image_details_list'
description: List of details for images uploaded by the given customer
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_server_error'
summary: List Card Image Details
tags:
- Cards
x-external: true
post:
description: 'Create a card image entity. Note that this does not include the image data itself. You can upload the image data via a subsequent uploadCardImageData request using the ID created here.
'
operationId: createCardImage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_card_image_request'
description: Details of the image to create
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/card_image_details'
description: Card image entity created
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Create Card Image
tags:
- Cards
x-external: true
/cards/images/{card_image_id}:
get:
description: Get card image details
operationId: getCardImageDetails
parameters:
- $ref: '#/components/parameters/card_image_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_image_details'
description: Details of the card image
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Get Card Image Details
tags:
- Cards
x-external: true
patch:
description: Update card image details. The only detail that can be updated is the card status as APPROVED or REJECTED.
operationId: updateCardImageDetails
parameters:
- $ref: '#/components/parameters/card_image_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update_card_image_request'
description: Details of the image to create
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_image_details'
description: Details of the card image
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Update Card Image Details
tags:
- Cards
x-external: true
/cards/images/{card_image_id}/data:
get:
description: Get card image data
operationId: getCardImageData
parameters:
- $ref: '#/components/parameters/card_image_id'
responses:
'200':
content:
image/jpeg:
schema:
format: binary
type: string
description: Image data
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Get Card Image Data
tags:
- Cards
x-external: true
post:
description: Upload card image data
operationId: uploadCardImageData
parameters:
- $ref: '#/components/parameters/card_image_id'
requestBody:
content:
image/jpeg:
schema:
format: binary
type: string
description: Binary image data
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_image_details'
description: Card image data was successfully uploaded
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Upload Card Image
tags:
- Cards
x-external: true
/cards/products:
get:
operationId: listCardProducts
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_product_list_response'
description: List of available Card Products
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_server_error'
summary: List Card Products
tags:
- Cards
x-external: true
/cards/single_use_token:
summary: Get Single-Use Token
post:
description: 'This endpoint returns a single-use access token. This type of token authorizes a single request to access API endpoints and data associated with a particular user
'
operationId: getClientSingleUseToken
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/single_use_token_request'
description: User token details
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/single_use_token_response'
description: Token Created
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable_entity'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Get single-use token
tags:
- Cards
x-external: true
components:
schemas:
card_activation_request:
properties:
activation_code:
description: An activation code provided with the card required to prove possession of the card
type: string
customer_id:
description: The ID of the customer for which card is being activated
example: 1acf447c-544b-41b4-94f9-bd96b03cc48e
format: uuid
type: string
required:
- activation_code
- customer_id
type: object
physical_card_issuance_request:
allOf:
- $ref: '#/components/schemas/physical_card'
- required:
- form
- customer_id
- account_id
- type
- card_product_id
type: object
example:
account_id: 1471cad8-077a-4382-9e64-e28ea526fbaf
card_product_id: aae9828b-c584-4971-86f9-c8ccc3ec3ad5
customer_id: d947fe22-f70c-4797-90fa-6cceb1245db0
form: PHYSICAL
type: DEBIT
single_use_token_request:
properties:
account_id:
description: The ID of the account to which the token will be linked
example: 9aea04bb-b7c7-46b5-817d-1af05e6b22f2
format: uuid
type: string
customer_id:
description: The ID of the customer to whom the token will be issued
example: e167fa0d-ee40-4a6e-b1ba-f61593fd254e
format: uuid
type: string
required:
- customer_id
- account_id
type: object
card_response:
discriminator:
mapping:
PHYSICAL: '#/components/schemas/physical_card_response'
VIRTUAL: '#/components/schemas/virtual_card_response'
propertyName: form
oneOf:
- $ref: '#/components/schemas/physical_card_response'
- $ref: '#/components/schemas/virtual_card_response'
virtual_card_plus_status:
allOf:
- $ref: '#/components/schemas/virtual_card'
- $ref: '#/components/schemas/virtual_card_response_status'
virtual_card_response_status:
allOf:
- $ref: '#/components/schemas/card_status_object'
- required:
- card_status
- status_reason
type: object
physical_card_format:
description: The format of a physical card product
enum:
- MAGNETIC_STRIPE
- CHIP
- CONTACT
- CONTACTLESS
- PHYSICAL_COMBO
type: string
update_card_image_request:
properties:
rejection_memo:
type: string
rejection_reason:
$ref: '#/components/schemas/card_image_rejection_reason'
status:
$ref: '#/components/schemas/card_image_status'
required:
- status
type: object
virtual_card_issuance_request:
allOf:
- $ref: '#/components/schemas/virtual_card'
- required:
- form
- customer_id
- account_id
- type
- card_product_id
type: object
example:
account_id: 378b3add-0045-4b07-8907-b5fff54f1858
card_product_id: 83ba2733-3fdd-49f2-bf79-c73b1ffa7437
customer_id: 122c0a4e-f955-4281-a5d9-bdd309776851
form: VIRTUAL
type: DEBIT
emboss_name:
description: The customer details to emboss on the card - Defaults to customer first and last name. Is limited to 21 characters. Valid characters are A-Z, a-z, 0-9, space ( ), period (.), comma (,), forward slash (/), hyphen (-), ampersand (&), single quote (').
properties:
line_1:
description: line 1
example: Krystal Bosco DVM
type: string
line_2:
description: line 2
example: Lesch, Schimmel and Green
type: string
required:
- line_1
type: object
physical_card_response_status:
allOf:
- $ref: '#/components/schemas/card_status_object'
- properties:
card_fulfillment_status:
$ref: '#/components/schemas/card_fulfillment_status'
fulfillment_details:
$ref: '#/components/schemas/fulfillment_details'
tracking_number:
deprecated: true
description: 'This contains all shipping details as provided by the card fulfillment provider, including the tracking
number. This field is deprecated. Instead, please use the fulfillment_details object, which includes a
field for just the tracking number.
'
example: Ship Date [2022-07-19], Shipping Method [UPS Next Day Air Saver]; Tracking Number [1ZW3268W1319325382]
readOnly: true
type: string
required:
- card_status
- status_reason
- card_fulfillment_status
type: object
single_use_token_response:
example:
customer_account_mapping_id: user_token
expires: '2000-01-23T04:56:07.000+00:00'
token: token
properties:
customer_account_mapping_id:
type: string
expires:
description: yyyy-MM-ddTHH:mm:ssZ
format: date-time
type: string
token:
type: string
required:
- expires
type: object
base_card:
allOf:
- $ref: '#/components/schemas/card_format'
- properties:
account_id:
description: The ID of the account to which the card will be linked
example: 98d3a7dd-8b7e-4b93-94b0-f5c9bcf88b39
format: uuid
type: string
bin:
description: The bin number
type: string
card_brand:
$ref: '#/components/schemas/card_brand'
card_product_id:
description: The card product to which the card is attached
example: f453e97a-83f8-4810-bdbc-8df324fc4241
format: uuid
type: string
creation_time:
description: The timestamp representing when the card issuance request was made
example: Tue Feb 08 2022 13:13:56 GMT+0000 (Coordinated Universal Time)
format: date-time
readOnly: true
type: string
customer_id:
description: The ID of the customer to whom the card will be issued
example: a33e874c-4fa5-4c6f-850f-0778ffa097e9
format: uuid
type: string
emboss_name:
$ref: '#/components/schemas/emboss_name'
expiration_month:
example: '06'
readOnly: true
type: string
expiration_time:
description: The timestamp representing when the card would expire at
example: Sat Mar 05 2022 01:33:52 GMT+0000 (Coordinated Universal Time)
format: date-time
readOnly: true
type: string
expiration_year:
example: '25'
readOnly: true
type: string
id:
description: Card ID
example: 57f266f7-5661-4e83-8a9a-ac19c76fb82f
format: uuid
readOnly: true
type: string
is_pin_set:
default: false
description: indicates whether a pin has been set on the card
example: true
readOnly: true
type: boolean
last_four:
description: The last 4 digits of the card PAN
example: '1234'
readOnly: true
type: string
last_modified_time:
description: The timestamp representing when the card was last modified at
example: Sun Nov 21 2021 04:23:47 GMT+0000 (Coordinated Universal Time)
format: date-time
readOnly: true
type: string
metadata:
$ref: '#/components/schemas/card_metadata'
reissue_reason:
description: "This is the reason the card needs to be reissued, if any. The reason determines several behaviours:\n - whether or not the new card will use the same PAN as the original card\n - the old card will be terminated and if so, when it will be terminated\n\nReason | Same PAN | Terminate Old Card\n---------------------- | -------- | ------------------\nEXPIRATION | yes | on activation\nLOST | no | immediately\nSTOLEN | no | immediately\nDAMAGED | yes | on activation\nVIRTUAL_TO_PHYSICAL(*) | yes | on activation\nPRODUCT_CHANGE | yes | on activation\nNAME_CHANGE(**) | yes | on activation\nAPPEARANCE | yes | on activation\n\n(*) VIRTUAL_TO_PHYSICAL is deprecated. Please use PRODUCT_CHANGE whenever reissuing from one\ncard product to another, including from a virtual product to a physical product.\n\n(**) NAME_CHANGE is deprecated. Please use APPEARANCE whenever reissuing in order to change the\nappearance of a card, such as the printed name or custom image.\n\nFor all reasons, the new card will use the same PIN as the original card and digital wallet tokens will\nreassigned to the new card\n"
enum:
- EXPIRATION
- LOST
- STOLEN
- DAMAGED
- NAME_CHANGE
- VIRTUAL_TO_PHYSICAL
- PRODUCT_CHANGE
- APPEARANCE
type: string
reissued_from_id:
description: 'When reissuing a card, specify the card to be replaced here. When getting a card''s details, if this card was issued as a reissuance of another card, this ID refers to the card was replaced. If this field is set, then reissue_reason must also be set.
'
example: 6d346154-0b81-493f-87b2-2996bf9a1c0a
format: uuid
type: string
reissued_to_id:
description: If this card was reissued, this ID refers to the card that replaced it.
example: abfc62db-8ea8-4218-a3fe-d534c34acc09
format: uuid
readOnly: true
type: string
type:
description: Indicates the type of card to be issued
enum:
- DEBIT
type: string
required:
- form
type: object
card_pin_status:
description: The status of the card PIN
enum:
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/synctera/refs/heads/main/openapi/synctera-cards-api-openapi.yml