Resource APIs to access and manage foundational data
openapi: 3.0.0
info:
description: APIs for interacting with Cadana Embedded Consumer Wallets
version: 1.0.0
title: Embedded Consumer Wallets Balances Resources API
termsOfService: https://cadanapay.com/terms-and-conditions
contact:
email: api@cadanapay.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.cadanapay.com
description: Prod Server
- url: https://dev-api.cadanapay.com
description: Dev Server
security:
- Authorization: []
tags:
- name: Resources
description: Resource APIs to access and manage foundational data
paths:
/v1/payment-requirements:
get:
summary: Payment corridor requirements
description: 'Returns a Draft-07 JSON-Schema fragment that specifies every field, enum, regex and conditional rule for the requested `countryCode` + `currency` + `paymentMethod`.
'
tags:
- Resources
operationId: getPaymentRequirements
parameters:
- name: countryCode
in: query
required: true
schema:
type: string
example: CO
- name: paymentMethod
in: query
required: true
schema:
type: string
example: bank
- name: currency
in: query
required: true
schema:
type: string
example: COP
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
description: Draft-07 JSON-Schema fragment
content:
application/schema+json:
schema:
$ref: '#/components/schemas/JSONSchemaDraft07'
examples:
colombiaBank:
$ref: '#/components/examples/coBankSchema'
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
/v1/providers:
get:
summary: Get payout providers
description: Get a list of providers for a given country code
tags:
- Resources
parameters:
- name: countryCode
in: query
required: true
description: The country code in ISO 3166-1 alpha-2 format
schema:
type: string
example: BR
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
$ref: '#/components/responses/GetProvidersResponse'
/v1/providers/resolve:
get:
summary: Resolve bank provider
description: "Resolves a bank code, SWIFT code, or ACH routing number to the corresponding bank name and details. The behaviour depends on the `paymentMethod` parameter:\n- **swift** — resolves an 8 or 11-character SWIFT/BIC code\n- **ach** — resolves a 9-digit US ACH routing number\n- **bank** — resolves against Cadana's internal bank provider list\n for the given currency"
tags:
- Resources
parameters:
- name: code
in: query
required: true
description: The bank code, SWIFT code, or routing number to look up
schema:
type: string
example: '341'
- name: currency
in: query
required: true
description: ISO 4217 currency code
schema:
type: string
example: BRL
- name: paymentMethod
in: query
required: true
description: 'Payment method type: swift, ach, or bank'
schema:
type: string
enum:
- swift
- ach
- bank
example: bank
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
$ref: '#/components/responses/ResolveCodeResponse'
'400':
$ref: '#/components/responses/BadRequestError'
/v1/payment-methods:
get:
summary: Get payment methods
description: Get a list of available payment methods for a given country code
tags:
- Resources
operationId: getPaymentMethods
parameters:
- name: countryCode
in: query
required: false
description: The country code in ISO 3166-1 alpha-2 format
schema:
type: string
example: BR
- name: paymentMethod
in: query
required: false
description: The payment method to filter by
schema:
type: string
example: bank
- name: currency
in: query
required: false
description: The currency to filter by
schema:
type: string
example: USD
- $ref: '#/components/parameters/XMultiTenantKey'
responses:
'200':
$ref: '#/components/responses/GetPaymentMethodsResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
5XX:
$ref: '#/components/responses/InternalError'
components:
responses:
GetPaymentMethodsResponse:
description: Available payment methods, one entry per country matching the query
content:
application/json:
schema:
type: array
items:
type: object
required:
- country
- paymentMethods
properties:
country:
type: string
description: The country code in ISO 3166-1 alpha-2 format
example: BR
countryName:
type: string
description: The country's display name
example: Brazil
paymentMethods:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
examples:
brazilPaymentMethods:
$ref: '#/components/examples/brazilPaymentMethods'
NotFoundError:
description: Requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
InternalError:
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
GetProvidersResponse:
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Provider'
ResolveCodeResponse:
description: Resolved bank provider details
content:
application/json:
schema:
$ref: '#/components/schemas/ResolvedProvider'
examples:
bankCodeLookup:
summary: Bank code lookup (BRL)
value:
bankName: Itaú Unibanco
countryCode: BR
city: ''
routingNumber: ''
swiftCode: ITAUBRSP
swiftCodeLookup:
summary: SWIFT code lookup (MXN)
value:
bankName: Banco Nacional de Mexico S.A.
countryCode: MX
city: Mexico City
routingNumber: ''
swiftCode: BNMXMXMM
achLookup:
summary: ACH routing number lookup (USD)
value:
bankName: JPMorgan Chase
countryCode: US
city: Tampa
routingNumber: '021000021'
swiftCode: CHASUS33
BadRequestError:
description: Bad input provided by client
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
schemas:
Provider:
type: object
required:
- code
- name
- countryCode
- currency
- type
properties:
code:
type: string
example: BR123
name:
type: string
example: Nubank Brazil
countryCode:
type: string
description: The country code in ISO 3166-1 alpha-2 format
example: BR
currency:
type: string
description: The currency in ISO 4217 format
example: BRL
type:
type: string
enum:
- bank
- momo
example: bank
NotFoundError:
description: Not Found
allOf:
- $ref: '#/components/schemas/Error'
example:
code: resource_not_found
message: Requested resource could not be found.
InternalError:
description: Internal server error
allOf:
- $ref: '#/components/schemas/Error'
example:
code: internal_error
message: An unexpected error occurred. Please try again later.
BadRequestError:
description: Bad input provided by client
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
params:
description: A map for meta data around the error that occurred
type: object
example:
code: invalid_request_body
message: The request body provided is not valid
params:
field: Value is invalid.
PaymentMethod:
type: object
required:
- type
- currency
- status
properties:
type:
type: string
description: The type of payment method
enum:
- bank
- swift
- proxy
- momo
- ach
example: bank
currency:
type: string
description: The currency in ISO 4217 format
example: KES
status:
type: string
description: The status of the payment method
enum:
- active
- inactive
example: active
JSONSchemaDraft07:
description: "This is a Draft-07 JSON Schema fragment. For the full meta-schema, see https://json-schema.org/draft-07/schema#. \nRely on the provided example for the expected structure.\n"
ResolvedProvider:
type: object
required:
- bankName
- countryCode
properties:
bankName:
type: string
description: The name of the resolved bank or financial institution
example: Itaú Unibanco
countryCode:
type: string
description: The country code in ISO 3166-1 alpha-2 format
example: BR
city:
type: string
description: City of the bank branch (populated for SWIFT and ACH lookups)
example: ''
routingNumber:
type: string
description: ACH routing number (populated for ACH lookups)
example: ''
swiftCode:
type: string
description: SWIFT/BIC code (populated when available)
example: ITAUBRSP
Error:
type: object
properties:
code:
description: A machine parsable error code
type: string
enum:
- invalid_request_body
- resource_not_found
- forbidden
- internal_error
message:
description: A human readable message describing the error
type: string
examples:
brazilPaymentMethods:
summary: Brazil Payment Methods
value:
- country: BR
countryName: Brazil
paymentMethods:
- type: bank
currency: BRL
status: active
- type: proxy
currency: BRL
status: active
- type: swift
currency: USD
status: active
coBankSchema:
summary: Colombia - bank payment method schema
value:
$schema: http://json-schema.org/draft-07/schema#
$id: https://api.cadana.com/schemas/paymentDetails.bank.CO.json
title: Colombia - bank payment details
type: object
additionalProperties: false
required:
- accountName
- accountNumber
- bankCode
- bankName
- accountType
- beneficiaryId
- address
- email
properties:
accountName:
type: string
maxLength: 60
accountNumber:
type: string
pattern: ^[0-9]{9,16}$
description: 9-16-digit Colombian account number
bankCode:
type: string
pattern: ^[A-Za-z0-9]{1,11}$
description: 1-11 alphanumeric bank code
accountType:
type: string
enum:
- Checking
- Saving
email:
type: string
format: email
maxLength: 100
beneficiaryId:
type: object
additionalProperties: false
required:
- type
- value
properties:
type:
type: string
enum:
- NIT
- CC
- CE
- TI
- PASS
value:
type: string
allOf:
- if:
properties:
type:
const: NIT
then:
properties:
value:
pattern: ^\d{9,11}$
- if:
properties:
type:
const: CC
then:
properties:
value:
pattern: ^\d{6,10}$
address:
type: object
additionalProperties: false
required:
- line1
- city
- countryCode
properties:
line1:
type: string
maxLength: 70
city:
type: string
maxLength: 50
countryCode:
const: CO
parameters:
XMultiTenantKey:
name: X-MultiTenantKey
in: header
required: false
schema:
type: string
description: Required when using a Platform API token. The tenant key identifying which business to operate on.
securitySchemes:
Authorization:
type: http
scheme: bearer
bearerFormat: API_SECRET_KEY
x-readme:
explorer-enabled: true
proxy-enabled: true
samples-enabled: true