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 External Cards (alpha) 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: Push and pull from cards
name: External Cards (alpha)
paths:
/external_cards:
get:
description: 'List external cards
'
operationId: listExternalCards
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/customer_id_query'
- $ref: '#/components/parameters/business_id_query1'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/external_card_list_response'
description: External cards list
'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 external cards
tags:
- External Cards (alpha)
x-external: true
/external_cards/{external_card_id}:
description: 'External Card
'
summary: Get External Card
get:
description: 'Get an external card
'
operationId: getExternalCard
parameters:
- $ref: '#/components/parameters/external_card_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/external_card_response'
description: External 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 a external card
tags:
- External Cards (alpha)
x-external: true
/external_cards/tokens:
post:
description: 'Create an external card from token - You must first tokenize the external card using the external card iframe. You will receive a token for the external card upon successful completion. This endpoint will persist the external card and associate it to a customer. The customer''s name and address should match that of the external card as entered in the iframe. <br>NB: Tokens should be associated right away. Tokens not associated within 30 mins of creation will be invalidated.</br> NB: If a valid business_id is provided, the address verification for the external card will be done against the address of the business. Otherwise, the address of the customer will be used. In either case, the name of the customer will be used to match the name of the cardholder.
'
operationId: createExternalCardFromToken
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/external_card_request'
description: Details of the card to create
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/external_card_response'
description: External card 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 external card from token
tags:
- External Cards (alpha)
x-external: true
/external_cards/transfers:
get:
description: 'List external card transfer
'
operationId: listExternalCardTransfers
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/customer_id_query_array1'
- $ref: '#/components/parameters/external_card_id_query'
- $ref: '#/components/parameters/originating_account_id_query_array'
- $ref: '#/components/parameters/external_transfer_type_query'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/transfer_list_response'
description: External transfer list
'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 external transfers
tags:
- External Cards (alpha)
x-external: true
post:
description: 'Create a external card transfer
'
operationId: createExternalCardTransfer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/transfer_request'
description: Details of the transfer to create
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/transfer_response'
description: External card transfer 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 external card transfer
tags:
- External Cards (alpha)
x-external: true
/external_cards/transfers/{transfer_id}:
description: 'External card transfer
'
summary: External Card Transfer
get:
description: 'Get an external transfer
'
operationId: getExternalCardTransfer
parameters:
- $ref: '#/components/parameters/transfer_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/transfer_response'
description: External card transfer 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 an external card transfer
tags:
- External Cards (alpha)
x-external: true
components:
responses:
internal_server_error:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Internal server error
bad_request:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: BadRequest
forbidden:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Forbidden error
unprocessable_entity:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Unprocessable entity request response
unauthorized:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Unauthorized
parameters:
external_card_id:
description: The unique identifier of an external card
in: path
name: external_card_id
required: true
schema:
example: 411e5190-c495-4344-9fb5-0a3c7bab0345
format: uuid
type: string
transfer_id:
description: The unique identifier of a transfer
in: path
name: transfer_id
required: true
schema:
example: 1b7767fe-7dcd-43d5-85cf-c4392bb3e830
format: uuid
type: string
originating_account_id_query_array:
explode: false
in: query
name: originating_account_id
required: false
schema:
items:
$ref: '#/components/schemas/originating_account_id'
type: array
style: form
x-external: true
external_card_id_query:
in: query
name: external_card_id
required: false
schema:
$ref: '#/components/schemas/external_card_id'
x-external: true
customer_id_query:
in: query
name: customer_id
required: false
schema:
$ref: '#/components/schemas/customer_id1'
x-external: true
page_token:
in: query
name: page_token
required: false
schema:
description: Optional pagination token to be provided to retrieve subsequent pages, returned from previous get
example: h50ffqz9q5
type: string
x-external: true
business_id_query1:
in: query
name: business_id
required: false
schema:
$ref: '#/components/schemas/business_id'
x-external: true
external_transfer_type_query:
description: The type of an external transfer
in: query
name: type
required: false
schema:
$ref: '#/components/schemas/transfer_type'
x-external: true
limit:
in: query
name: limit
required: false
schema:
default: 100
description: 'Maximum number of objects to return per page. If the limit is greater than 100, then it will be set to 100.
'
example: 100
minimum: 1
type: integer
x-external: true
customer_id_query_array1:
explode: false
in: query
name: customer_id
required: false
schema:
items:
$ref: '#/components/schemas/customer_id1'
type: array
style: form
x-external: true
schemas:
external_card_request:
properties:
business_id:
$ref: '#/components/schemas/business_id'
customer_id:
$ref: '#/components/schemas/customer_id1'
token:
description: The token that was returned via tokenization iframe
type: string
required:
- token
- customer_id
type: object
external_card_id:
description: The unique identifier of external card
example: 7aeb712d-e9c7-42eb-965f-ce19507b17f8
format: uuid
type: string
business_id:
description: The unique identifier of a business
example: 4d742b70-9176-4f4b-bcbb-b42fe29b106d
format: uuid
type: string
external_card_list_response:
allOf:
- properties:
external_cards:
description: Array of External Cards
items:
$ref: '#/components/schemas/external_card_response'
type: array
required:
- external_cards
type: object
- $ref: '#/components/schemas/paginated_response'
transfer_response:
properties:
account_id:
description: The ID of the account to which the card will be linked
example: a4037077-95cc-4746-806e-e19f32a2a5ab
format: uuid
type: string
amount:
description: Amount of the transfer in cents
type: integer
country_code:
description: ISO-3166-1 Alpha-2 country code
example: US
type: string
created_time:
example: '2020-01-01T00:00:00.000Z'
format: date-time
type: string
currency:
$ref: '#/components/schemas/currency_code'
customer_id:
description: The ID of the customer for which card is being activated
example: a2d8305b-38bc-4f9e-a860-66b4ccbc52bc
format: uuid
type: string
id:
description: The id of the transfer
type: string
last_modified_time:
example: '2020-01-01T00:00:00.000Z'
format: date-time
type: string
status:
description: The status of the transfer
enum:
- SUCCEEDED
- PENDING
- FAILED
type: string
transaction_id:
description: The transaction ID
format: uuid
type: string
type:
$ref: '#/components/schemas/transfer_type'
required:
- account_id
- id
- amount
- currency
- status
- customer_id
- country_code
- created_time
- last_modified_time
- type
type: object
transfer_type:
description: 'Type of operation for transfer.
Type | Description
--- | ---
PUSH | Push fund to the external card from the account_id
PULL | Pull funds from the external card to the account_id.
'
enum:
- PULL
- PUSH
example: PULL
type: string
transfer_request:
description: Push to card or pull from card
properties:
amount:
description: Amount of the transfer in cents
type: integer
currency:
$ref: '#/components/schemas/currency_code'
external_card_id:
description: The ID of the external card from/to which the transfer will be initiated/received
example: b2710751-b575-47d0-a09b-da0994553d93
format: uuid
type: string
originating_account_id:
description: The ID of the account to which the transfer will be initiated/received
example: 3e2a2f28-4910-4934-be22-ded51f926b76
format: uuid
type: string
type:
$ref: '#/components/schemas/transfer_type'
required:
- originating_account_id
- amount
- currency
- type
- external_card_id
type: object
processor:
description: The transaction processor
enum:
- VISA_V1
- MASTERCARD_V1
example: MASTERCARD_V1
type: string
originating_account_id:
description: The unique identifier of an originating account
example: a6f8870c-1e7e-45ba-833d-cbc1eead9d2d
format: uuid
type: string
customer_id1:
description: The unique identifier of a customer
example: 8da2b02b-81f2-41f3-a32e-041eb8ccd825
format: uuid
type: string
currency_code:
description: ISO 4217 Alpha-3 currency code
example: USD
maxLength: 3
minLength: 3
type: string
error:
properties:
detail:
description: a human-readable string explaining this particular error
example: 'missing required fields: first_name, dob'
type: string
status:
description: the HTTP status code for this response
example: 400
type: integer
title:
description: a human-readable string for this general category of error
example: Bad Request Body
type: string
type:
description: a URI that identifies this general category of error
example: https://dev.synctera.com/errors/bad-request-body
type: string
title: Standard error response (RFC 7807 problem report)
type: object
transfer_list_response:
allOf:
- properties:
external_transfers:
description: Array of External transfer
items:
$ref: '#/components/schemas/transfer_response'
type: array
required:
- external_transfers
type: object
- $ref: '#/components/schemas/paginated_response'
paginated_response:
properties:
next_page_token:
description: If returned, use the next_page_token to query for the next page of results. Not returned if there are no more rows.
example: d61grelm5f
type: string
title: Paginated List response
type: object
external_card_verifications:
description: Verify card passed AVS and CVV checks in order to use PULL transfer. Verify card is eligible to receive push-to-card disbursements. For example, the inquiry_details object will contain a push_funds_block_indicator attribute that indicates if it is eligible for push-to-card disbursements.
properties:
address_verification_results:
description: 'Address verification results
Status | Description
--- | ---
VERIFIED | Address verified
NOT_VERIFIED | Address not verified
ADDRESS_NO_MATCH | Postal/ZIP match, street addresses do not match or street address not included in request
'
enum:
- VERIFIED
- NOT_VERIFIED
- ADDRESS_NO_MATCH
type: string
card_type:
description: Indicates whether the external card is credit, debit, prepaid, deferred debit, or charge.
enum:
- CREDIT
- DEBIT
- CHARGE_PAID
- PREPAID
- DEFERRED_DEBIT
type: string
cvv2_result:
description: "Card Verification Value results\n\nStatus | Description\n--- | ---\nVERIFIED | CVV and expiration dates verified\nINCORRECT | Either CVV or expiration date is incorrect\nNOT_SUPPORTED | \tIssuer does not participate in CVV2 service\n"
enum:
- VERIFIED
- INCORRECT
- NOT_SUPPORTED
type: string
fast_funds_indicator:
description: Indicates if card is Fast Funds eligible (i.e. if the funds will settle in 30 mins or less). If not eligible, typically funds will settle within 2 business days.
type: boolean
online_gambling_block_indicator:
description: Indicates if the card can receive push-payments for online gambling payouts.
type: boolean
processor:
$ref: '#/components/schemas/processor'
push_funds_block_indicator:
description: Indicates if the associated card can receive push-to-card disbursements.
type: boolean
state:
enum:
- SUCCEEDED
- FAILED
type: string
type: object
external_card_response:
properties:
created_time:
example: '2020-01-01T00:00:00.000Z'
format: date-time
type: string
currency:
$ref: '#/components/schemas/currency_code'
customer_id:
$ref: '#/components/schemas/customer_id1'
expiration_month:
example: '06'
readOnly: true
type: string
expiration_year:
example: '25'
readOnly: true
type: string
id:
description: External card ID
type: string
last_four:
description: The last 4 digits of the card PAN
example: '1234'
readOnly: true
type: string
last_modified_time:
example: '2020-01-01T00:00:00.000Z'
format: date-time
type: string
name:
description: The external card holder name
example: Jean Valjean
type: string
verifications:
$ref: '#/components/schemas/external_card_verifications'
required:
- id
- currency
- customer_id
- expiration_month
- expiration_year
- last_four
- name
type: object
securitySchemes:
bearerAuth:
bearerFormat: api_key
scheme: bearer
type: http
x-readme:
explorer-enabled: true
proxy-enabled: true
samples-enabled: true