openapi: 3.0.2
info:
title: Gateway Services
description: >-
Self onboarding services for merchants to register on the platform, create
wallets, and perform withdrawals or payouts to their designated settlement
and external beneficiary accounts.
contact:
name: Standards & Developer Hub
url: https://tts.sandbox.developer.citi.com/citiconnect/
email: developer-support@citi.com
version: 1.0.0
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
description: production gateway url
- url: https://sandbox.b2b.api.icg.citi.com/citiconnect/sb/gatewayservices
description: sbox url
tags:
- name: MerchantCreation
description: Merchant onboarding and management operations
- name: File
description: File management
- name: Certification
description: KYC certification submission and retrieval
- name: Rfi
description: Request for Information operations
- name: Wallet
description: Wallet management and balance operations
- name: LinkAccount
description: Account linkage operations for external payments
- name: Payment
description: Payout and payment query operations
- name: Fx
description: FX Rate Inquiry
- name: Reporting
description: Transaction and balance reporting operations
security:
- oAuth2:
- /authenticationservices/v1
paths:
/merchants/v1/onboard:
post:
tags:
- MerchantCreation
summary: Create merchant
description: >-
This endpoint allows you to create or onboard a merchant on the Payment
Service Provider platform, validate onboarding data, and receive a
merchant identifier for downstream service requests.
operationId: merchantCreation
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Idempotency-Id'
- $ref: '#/components/parameters/Country-Code'
requestBody:
required: true
description: >-
This request body contains the necessary merchant details for creating
a new merchant entity in PSP.
content:
application/json:
schema:
$ref: '#/components/schemas/Merchant-Onboarding-Request'
examples:
Merchant-Creation-For-Enterprise-Request:
$ref: >-
#/components/examples/Merchant-Creation-For-Enterprise-Request-Example
responses:
'200':
description: >-
This response body will return the unique identifier for the newly
created merchant along with status.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Merchant-Onboarding-Response'
examples:
merchant_creation_success_response:
$ref: >-
#/components/examples/Merchant-Creation-Success-Response-Example
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
get:
summary: Get Merchant ID
description: >-
Use the partner user ID on your platform to look up the merchant ID on
the payment service provider platform (the merchant_id returned when you
create a merchant).
operationId: getMerchantId
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- MerchantCreation
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Partner-User-Id'
responses:
'200':
description: Merchant ID retrieved successfully.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Get-Merchant-Onboarding'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/documents/upload:
post:
tags:
- File
summary: Documents upload for verification
description: >-
This endpoint is where you securely upload files to send to payment
service provider, including KYC and KYB documentation to support
customer verification.
operationId: fileUpload
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Idempotency-Id'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Country-Code'
requestBody:
required: true
description: >-
Multipart file upload allows client to send files (e.g., images,
documents) as part of a request. The request content type must be
multipart/form-data. Supported formats are image/png, image/jpeg,
image/jpg, image/bmp, application/pdf. Supported file size <10000000
bytes. Client should pass single file per request
content:
multipart/form-data:
schema:
title: Upload-Document-Request
type: object
required:
- file
properties:
file:
type: string
format: binary
description: The file to upload
maxLength: 10000000
additionalProperties: false
encoding:
file:
contentType: image/png, image/jpeg, image/jpg, image/bmp, application/pdf.
headers:
Content-Length:
schema:
type: integer
maximum: 10000000
responses:
'200':
description: Merchant ID creation Response
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/File-Upload-Response'
examples:
File-Upload-Positive-Response:
$ref: '#/components/examples/File-Upload-Positive-Response-Example'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
deprecated: false
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/documents/download:
post:
summary: File Download
description: >-
Retrieve secure download links for previously uploaded merchant files by
providing one or more file identifiers, allowing clients to fetch
supported documents in a controlled and traceable manner.
operationId: downloadFile
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- File
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Merchant-Id'
requestBody:
content:
application/json:
schema:
title: Download-Document-Request
type: object
properties:
file_ids:
type: array
minItems: 1
maxItems: 25
items:
type: string
maxLength: 128
description: >-
File ID returned by PingPong at upload. List file ids to get
download links for multiple files in one call.
required:
- file_ids
example:
file_ids:
- N1234567891011121314151620
- N1234567891011121314151621
- N1234567891011121314151622
responses:
'200':
description: File downloaded successfully.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/File-Download-Response'
examples:
File-Download-Response-Example:
$ref: '#/components/examples/File-Download-Response-Example'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
deprecated: false
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/certification:
post:
summary: Submit Certification
description: >-
This endpoint allows you to submit certification information to verify a
merchant or update existing KYC details, and trigger review workflows
required for compliance and account readiness.
operationId: submitCertification
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Certification
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Idempotency-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Operation'
requestBody:
required: true
description: Request body for the certification request.
content:
application/json:
schema:
$ref: '#/components/schemas/Certification-Request'
examples:
Certification-Request:
$ref: '#/components/examples/Certification-Request'
Certification-Request-CN:
$ref: '#/components/examples/Certification-Request-Cn'
Certification-Request-HK:
$ref: '#/components/examples/Certification-Request-Hk'
responses:
'200':
description: Certification request accepted for processing.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Sync-Response'
examples:
Certification-Save-Acknowledgement:
$ref: '#/components/examples/Certification-Save-Acknowledgement'
Certification-Submit-Acknowledgement:
$ref: '#/components/examples/Certification-Submit-Acknowledgement'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
callbacks:
certification-webhook:
'{$notificationURL}':
post:
summary: Certification Webhook
description: >-
Webhook notification for certification status updates. Pushes
updates of the KYC certification request.
operationId: certificationWebhook
parameters:
- $ref: '#/components/parameters/Event-Type'
- $ref: '#/components/parameters/Event-Name'
- $ref: '#/components/parameters/Apim-Guid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook-Certification'
examples:
Certification-Approved-Webhook-Example:
$ref: >-
#/components/examples/Certification-Approved-Webhook-Example
Certification-Declined-Webhook-Example:
$ref: >-
#/components/examples/Certification-Declined-Webhook-Example
Certification-Rfi-Pending-Webhook-Example:
$ref: >-
#/components/examples/Certification-Rfi-Pending-Webhook-Example
responses:
'200':
description: Webhook received successfully.
rfi:
'{$notificationURL}':
post:
operationId: rfiNotification
summary: Request for Information (RFI) Notification Webhook
description: This webhook pushes notifications of Request for Information.
tags:
- RFI Webhook
parameters:
- $ref: '#/components/parameters/Event-Type'
- $ref: '#/components/parameters/Event-Name'
- $ref: '#/components/parameters/Apim-Guid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RFI-Notification'
examples:
rfi-notification-example:
$ref: '#/components/examples/RFI-Notification-Example'
responses:
'200':
description: Webhook received successfully.
get:
summary: Get Certification
description: >-
Check the status of a merchant's KYC review using the merchant_id
returned during onboarding, including progress indicators, review
outcomes, and required follow-up actions when applicable.
operationId: getCertification
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Certification
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Merchant-Id'
responses:
'200':
description: Certification details retrieved successfully.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Get-Certification-Response'
examples:
Get-Certification:
$ref: '#/components/examples/Get-Certification'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/wallets/activation:
post:
summary: Activate wallet for virtual accounts
description: >-
Use this endpoint to apply for Virtual Accounts (VAs) to start
sending/receiving funds. You can only apply for VAs when the kyc_status
of your account is APPROVED.
operationId: activateWallet
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Wallet
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Idempotency-Id'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Country-Code'
requestBody:
required: true
description: >-
This section holds the request parameters for virtual account
activation.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet-Activation-Request'
examples:
wallet-activation-request:
$ref: '#/components/examples/Wallet-Activation-Request-Example'
responses:
'200':
description: >-
This section holds the successful response for virtual account
activation.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Sync-Response'
examples:
wallet-activation-response:
$ref: '#/components/examples/Wallet-Activation-Response-Example'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
callbacks:
walletActivationWebhook:
'{$notificationURL}':
post:
summary: Wallet activation webhook notification
description: >-
Webhook notification sent when a wallet activation status
changes.
operationId: walletActivationWebhookNotification
tags:
- Wallet
parameters:
- $ref: '#/components/parameters/Event-Type'
- $ref: '#/components/parameters/Event-Name'
- $ref: '#/components/parameters/Apim-Guid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook-Wallet-Activation'
examples:
Wallet-Activation-Available-Webhook-Example:
$ref: >-
#/components/examples/Wallet-Activation-Available-Webhook-Example
Wallet-Activation-Closed-Webhook-Example:
$ref: >-
#/components/examples/Wallet-Activation-Closed-Webhook-Example
wallet-activation-Declined-webhook:
$ref: >-
#/components/examples/Wallet-Activation-Declined-Webhook-Example
responses:
'200':
description: Webhook received successfully.
/merchants/v1/wallets/balances:
get:
summary: Get wallet balances
description: >
Retrieve available and related wallet account balance information for
the specified merchant and account filters, enabling reconciliation,
reporting, and operational funding decisions.
operationId: getWalletBalances
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Wallet
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Currency-Code'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Virtual-Account-Id'
responses:
'200':
description: This section holds the virtual balances.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Get-Wallet-Balances'
examples:
get-wallet-balances-response:
$ref: '#/components/examples/Get-Wallet-Balances-Response-Example'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/wallets:
get:
summary: Get wallet status
description: >-
Check the status of virtual accounts using the virtual_account_id
returned from wallet activation, and review account state details needed
to determine operational readiness and lifecycle stage.
operationId: getWallet
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Wallet
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Virtual-Account-Id'
responses:
'200':
description: >-
This section holds the successful response for virtual account
status inquiry.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Get-Wallet-Activation-Response'
examples:
get-wallet-response:
$ref: '#/components/examples/Get-Wallet-Response-Example'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/link-accounts:
post:
summary: Link external account for payments
description: >-
Use this endpoint to verify an external creditor account and receive a
creditor_id for successfully validated beneficiaries, so the account can
be used in subsequent payout transactions.
operationId: linkAccount
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- LinkAccount
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Idempotency-Id'
- $ref: '#/components/parameters/Country-Code'
requestBody:
required: true
description: This section holds the request parameters used to verify the Creditor.
content:
application/json:
schema:
$ref: '#/components/schemas/Link-Account-Request'
examples:
account-linkage-request:
$ref: '#/components/examples/Account-Linkage-Request-Example'
Account-Linkage-Request-Example-HK:
$ref: '#/components/examples/Account-Linkage-Request-Example-HK'
Account-Linkage-Request-Example-CN:
$ref: '#/components/examples/Account-Linkage-Request-Example-CN'
responses:
'200':
description: >-
This section holds the successful response for creditor
verification.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Sync-Response'
examples:
account-linkage-response:
$ref: '#/components/examples/Account-Linkage-Response-Example'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
callbacks:
accountLinkageWebhook:
'{$notificationURL}':
description: >-
This endpoint used to push the status notification for creditor
verification.
post:
summary: Account linkage webhook notification
description: >-
Webhook notification sent when an account linkage status
changes. This callback is triggered for status updates on linked
accounts.
operationId: accountLinkageWebhookNotification
tags:
- Account-Linkage
parameters:
- $ref: '#/components/parameters/Event-Type'
- $ref: '#/components/parameters/Event-Name'
- $ref: '#/components/parameters/Apim-Guid'
requestBody:
description: >-
This section holds the request parameters for creditor
verification notification.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook-Link-Account'
examples:
Account-Linkage-Available-Webhook-Example:
$ref: >-
#/components/examples/Account-Linkage-Available-Webhook-Example
Account-Linkage-Declined-Webhook-Example:
$ref: >-
#/components/examples/Account-Linkage-Declined-Webhook-Example
responses:
'200':
description: Webhook received successfully.
get:
summary: Get linked account details
description: >-
You can use this to check the status of the creditor. Creditor must be
verified and have an 'AVAILABLE' status before sending external
payments.
operationId: getLinkedAccount
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- LinkAccount
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Creditor-Id'
- $ref: '#/components/parameters/Creditor-Partner-User-Id'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Page-No'
responses:
'200':
description: >-
This section holds the successful response for creditor verification
inquiry.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
Pagination-Metadata:
description: >-
This header contains a JSON object with details about the
response. The full schema is available in the
'Pagination-Metadata' schema section below
schema:
$ref: '#/components/schemas/Pagination-Metadata'
content:
application/json:
schema:
$ref: '#/components/schemas/Get-Link-Account-Response'
examples:
get-account-linkage-response:
$ref: '#/components/examples/Get-Account-Linkage-Response-Example'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/fx-rate:
post:
summary: FX Query
description: >-
You can use this to get fx rate to be used for transaction. The latest
rate you get is valid for 5 minutes , during which time you can use this
rate to transaction
operationId: fxQuery
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Fx
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Idempotency-Id'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Country-Code'
requestBody:
description: This section holds the request parameters for FX Rate Inquiry.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Fx-Query-Request'
examples:
fxquery-request:
$ref: '#/components/examples/Fx-Query-Request-Example'
responses:
'200':
description: FX Query completed successfully.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Fx-Query-Response'
examples:
success-response:
$ref: '#/components/examples/Fx-Query-Success-Example'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/payments:
post:
summary: Create Payment
description: >-
Make a payment from your account held with Citi to a virtual account
held with Citi or from the virtual account held with Citi to an external
bank account. Virtual account must be in "AVAILABLE" status.
operationId: createPayout
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Payment
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Idempotency-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Optional-Merchant-Id'
- $ref: '#/components/parameters/Wallet-Payment'
requestBody:
x-skip-validation: true
required: true
description: This section contains the request parameters for payment initiation.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment-Request'
examples:
Payment-To-Wallet-Request:
$ref: '#/components/examples/Payment-To-Wallet-Request'
Payment-To-External-Request:
$ref: '#/components/examples/Payment-To-External-Request'
responses:
'202':
description: Payout request accepted for processing.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Payment-Response'
examples:
Payment-Validation-Success-Example:
$ref: '#/components/examples/Payment-Validation-Success-Example'
Payment-Validation-Partial-Rejection-Example:
$ref: >-
#/components/examples/Payment-Validation-Partial-Rejection-Example
'400':
description: Bad Request
content:
application/json:
schema:
title: Payment-Bad-Request-Response
oneOf:
- $ref: '#/components/schemas/Gateway-Error-Response'
- $ref: '#/components/schemas/Service-Error-Response'
- $ref: '#/components/schemas/Payment-Response'
examples:
Payment-Validation-Full-Rejection-Example:
$ref: >-
#/components/examples/Payment-Validation-Full-Rejection-Example
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
callbacks:
payout-webhook:
'{$notificationURL}':
post:
summary: Payout Webhook
description: Webhook notification for payment status updates.
operationId: payoutWebhook
parameters:
- $ref: '#/components/parameters/Event-Type'
- $ref: '#/components/parameters/Event-Name'
- $ref: '#/components/parameters/Apim-Guid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook-Payment-Request'
examples:
Payment-To-Wallet-Rejected-Webhook:
$ref: >-
#/components/examples/Payment-To-Wallet-Rejected-Webhook
Payment-To-External-Rejected-Webhook:
$ref: >-
#/components/examples/Payment-To-External-Rejected-Webhook
Payment-To-Wallet-Success-Webhook:
$ref: >-
#/components/examples/Payment-To-Wallet-Success-Webhook
Payment-To-External-Success-Webhook:
$ref: >-
#/components/examples/Payment-To-External-Success-Webhook
responses:
'200':
description: Webhook received successfully.
inbound-payment:
'{$notificationURL}':
post:
operationId: inboundPaymentNotification
summary: Inbound Payment Notification Webhook
description: >-
This webhook pushes notifications for the payment received in
your virtual account.
tags:
- Inbound Webhook
parameters:
- $ref: '#/components/parameters/Event-Type'
- $ref: '#/components/parameters/Event-Name'
- $ref: '#/components/parameters/Apim-Guid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Inbound-Payment-Notification'
examples:
inbound-payment-example:
$ref: >-
#/components/examples/Inbound-Payment-Notification-Example
responses:
'200':
description: Webhook received successfully.
get:
summary: Get Payment
description: >-
Query the status and detailed attributes of a payment using supported
identifiers, including processing state, settlement outcomes, and
reference information needed for reconciliation and customer support.
operationId: getPayment
tags:
- Payment
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Optional-Merchant-Id'
- $ref: '#/components/parameters/Uetr'
- $ref: '#/components/parameters/End-To-End-Id'
responses:
'200':
description: Payment details retrieved successfully.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Get-Payment-Response'
examples:
Get-Payment-To-Wallet:
$ref: '#/components/examples/Get-Payment-To-Wallet'
Get-Payment-To-External:
$ref: '#/components/examples/Get-Payment-To-External'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
deprecated: false
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/rfi:
post:
summary: RFI Response
description: >-
Allows you to respond to the RFI request with answers. This API allows
you to reply to either a single or multiple questions in one call,
depending on how you choose to respond.
operationId: saveRfiResponse
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Rfi
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Idempotency-Id'
requestBody:
description: This section holds the request parameters for RFI.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Rfi-Save-Request'
examples:
Rfi-Response:
$ref: '#/components/examples/Rfi-Response'
responses:
'200':
description: RFI response accepted for processing.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Rfi-Save-Response'
examples:
Rfi-Response-Acknowledgement:
$ref: '#/components/examples/Rfi-Response-Acknowledgement'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
get:
summary: RFI Query
description: >-
Retrieves details of single RFI using the given RFI ID or returns a list
of RFIs raised for your account.
operationId: queryRfi
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Rfi
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/Rfi-Id'
- $ref: '#/components/parameters/Type'
- $ref: '#/components/parameters/From-Date'
- $ref: '#/components/parameters/To-Date'
- $ref: '#/components/parameters/Page-No'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Rfi-Status'
responses:
'200':
description: RFI details retrieved successfully.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
Pagination-Metadata:
description: >-
This header contains a JSON object with details about the
response. The full schema is available in the
'Pagination-Metadata' schema section below
schema:
$ref: '#/components/schemas/Pagination-Metadata'
content:
application/json:
schema:
$ref: '#/components/schemas/Rfi-Query-Response'
examples:
Get-Rfi:
$ref: '#/components/examples/Get-Rfi'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/rfi/submit:
post:
summary: RFI Submit
description: >-
Allows you to submit an RFI. After submitting status will be updated to
CLOSED. CLOSED means the submission of replies is now disabled.
operationId: submitRfiResponse
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Rfi
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Idempotency-Id'
- $ref: '#/components/parameters/Merchant-Id'
requestBody:
description: This section holds the request parameters for RFI Submit.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Rfi-Submit-Request'
examples:
Rfi-Submit:
$ref: '#/components/examples/Rfi-Submit'
responses:
'200':
description: RFI submitted successfully for processing.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
content:
application/json:
schema:
$ref: '#/components/schemas/Rfi-Submit-Response'
examples:
Rfi-Submit-Acknowledgement:
$ref: '#/components/examples/Rfi-Submit-Acknowledgement'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'409':
$ref: '#/components/responses/Conflict'
'415':
$ref: '#/components/responses/Unsupported-Media-Type'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/transactions:
get:
summary: Transaction Reporting
description: >-
Retrieves list and details of transactions, suitable for reporting
purposes such as ledgers, finance Operations and analytics.
operationId: getTransactions
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Reporting
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/From-Date-Time'
- $ref: '#/components/parameters/To-Date-Time'
- $ref: '#/components/parameters/Page-No'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Uetr'
- $ref: '#/components/parameters/Payment-Type'
- $ref: '#/components/parameters/Reporting-Status'
responses:
'200':
description: Transaction report retrieved successfully.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
Pagination-Metadata:
description: >-
This header contains a JSON object with details about the
response. The full schema is available in the
'Pagination-Metadata' schema section below
schema:
$ref: '#/components/schemas/Pagination-Metadata'
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction-Report-Response'
examples:
Transaction-Report:
$ref: '#/components/examples/Transaction-Report'
Transaction-Report-For-WITHDRAW-&-INBOUND:
$ref: >-
#/components/examples/Transaction-Report-For-WITHDRAW-INBOUND
Transaction-Report-For-PAYOUT:
$ref: '#/components/examples/Transaction-Report-For-PAYOUT'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
/merchants/v1/balance-report:
get:
summary: Balance Report
description: >-
This helps financial reconciliation, enabling tracking of opening and
closing balances for a period, along with updated running balances
following each transaction. This report helps you track changes to your
account balance and reconcile the balance whenever required.
operationId: getBalanceReport
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
tags:
- Reporting
parameters:
- $ref: '#/components/parameters/Client-Id'
- $ref: '#/components/parameters/Country-Code'
- $ref: '#/components/parameters/Merchant-Id'
- $ref: '#/components/parameters/From-Date-Time'
- $ref: '#/components/parameters/To-Date-Time'
- $ref: '#/components/parameters/Page-No'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Uetr'
- $ref: '#/components/parameters/Currency-Code'
- $ref: '#/components/parameters/Virtual-Account-Id'
responses:
'200':
description: Balance report retrieved successfully.
headers:
apim-guid:
$ref: '#/components/headers/Apim-Guid'
Pagination-Metadata:
description: >-
This header contains a JSON object with details about the
response. The full schema is available in the
'Pagination-Metadata' schema section below
schema:
$ref: '#/components/schemas/Pagination-Metadata'
content:
application/json:
schema:
$ref: '#/components/schemas/Balance-Report-Response'
examples:
Balance-Report:
$ref: '#/components/examples/Balance-Report'
'400':
$ref: '#/components/responses/Bad-Request'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'405':
$ref: '#/components/responses/Method-Not-Allowed'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
'504':
$ref: '#/components/responses/Gateway-Timeout'
security:
- oAuth2:
- /authenticationservices/v1
components:
securitySchemes:
oAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://b2b.api.icg.citi.com/authenticationservices/v3/oauth/token
scopes:
/authenticationservices/v1: Access to marketplace management APIs
headers:
Apim-Guid:
description: >-
Unique system generated reference number generated by Citi. Refer to
this number in case of any discrepancy reporting to a Citi
representative.
schema:
type: string
maxLength: 128
minLength: 1
title: Apim-Guid
required: true
example: na-apimgwgtds04~4a98cbc5-d813-4e65-bc81-d70f0f87f6ec
parameters:
Client-Id:
in: query
name: client_id
description: >-
Your unique identification, same as the identification you use for OAuth
token generation, Citi shared with you during your CitiConnect API
onboarding.
schema:
type: string
title: Client-Id
example: 6d3cf821-db6d-496d-bec0-064a362e9c31
minimum: 1
maximum: 128
required: true
Apim-Guid:
in: header
name: Apim-Guid
description: >-
Unique system generated reference number generated by Citi. Refer to
this number in case of any discrepancy reporting to a Citi
representative.
schema:
type: string
maxLength: 128
minLength: 1
title: Apim-Guid
required: true
example: na-apimgwgtds04~4a98cbc5-d813-4e65-bc81-d70f0f87f6ec
Optional-Merchant-Id:
in: header
name: Merchant-Id
description: >-
CITI generated Merchant ID during merchant creation. It is mandatory for
payment to external.
schema:
type: string
title: Merchant-Id
minLength: 1
maxLength: 36
example: ec689822-9864-4c4d-9d68-22246762901
Merchant-Id:
in: header
name: Merchant-Id
description: CITI generated Merchant ID during merchant creation.
schema:
type: string
title: Merchant-Id
minLength: 1
maxLength: 36
example: ec689822-9864-4c4d-9d68-22246762901
required: true
Idempotency-Id:
in: header
name: Idempotency-Id
description: >-
Your unique identification for a POST request
- Maximum length is 128.
-CitiConnect API responds with an error (HTTP status 4XX) if your POST
request idempotency identification value is a duplicate across a recent
history of idempotency identifications in Citi's database.
- If you don't receive any response (HTTP status 2XX, 4XX or 5XX) from
Citi to your POST request and you wish to retry, reinitiate your request
with the same idempotency identification to prevent accidental duplicate
payment.
schema:
type: string
title: Idempotency-Id
minLength: 1
maxLength: 128
example: a44cbb606de4edb9a7a123414bba3bb
required: true
Country-Code:
in: header
name: Country-Code
description: Marketplace's country code.
schema:
pattern: ^[A-Z]{2,2}$
type: string
title: Country-Code
example: US
required: true
Virtual-Account-Id:
name: virtual_account_id
in: query
description: The unique ID returned when you call wallet activation.
schema:
type: string
title: virtual_account_id
minLength: 1
maxLength: 36
example: R200801012359590001
Creditor-Id:
name: creditor_id
in: query
description: The unique creditor identifier returned when you call link account.
schema:
type: string
title: creditor_id
minLength: 1
maxLength: 36
example: R202501080950209789
Creditor-Partner-User-Id:
name: creditor_partner_user_id
in: query
description: The unique creditor identifier of your system.
schema:
type: string
title: creditor_partner_user_id
minLength: 1
maxLength: 50
example: P298UI839KADY381
Event-Type:
name: Event-Type
in: header
required: true
description: >-
Type of event (e.g., CERTIFICATION, WALLET_ACTIVATION, LINK_ACCOUNT,
PAYMENT, INBOUND, RFI).
schema:
type: string
title: event-type
minLength: 1
maxLength: 64
example: Webhook
Event-Name:
name: Event-Name
in: header
description: Name of event (e.g., PAYOUT, PAYIN).
schema:
type: string
title: event-name
minLength: 1
maxLength: 64
example: Payout
Currency-Code:
name: currency_code
in: query
required: false
description: Query the balance for a specific currency code.
schema:
type: string
title: currency_code
pattern: ^[A-Z]{3}$
example: USD
Partner-User-Id:
name: partner_user_id
in: query
required: true
description: The unique seller identifier of your system.
schema:
type: string
title: partner_user_id
minLength: 1
maxLength: 50
example: PartnerUserID1234
Limit:
name: limit
in: query
required: false
description: Number of results per page (default- 50).
schema:
type: integer
title: limit
minimum: 1
maximum: 100
default: 50
Page-No:
name: page_no
in: query
required: false
description: Page number (default- 1).
schema:
type: integer
title: page_no
minimum: 1
maximum: 5000
default: 1
Uetr:
name: uetr
required: false
in: query
description: The unique payment identifier assigned during payment initiation.
schema:
type: string
title: uetr
minLength: 1
maxLength: 36
End-To-End-Id:
name: end_to_end_id
in: query
required: false
description: >-
The unique payment identifier from your system. If the request is for
payment to wallet, this field should contain maximum 16 character.
schema:
type: string
title: end_to_end_id
minLength: 1
maxLength: 35
From-Date-Time:
name: from_date_time
in: query
required: false
description: >-
The start date for the requested period. Pattern: YYYY-MM-DDTHH:mm:ssZ.
When from_date_time is used to_date_time is required and the supported
range should be 1 year.
schema:
type: string
title: from_date_time
format: date-time
example: '2024-03-17T10:30:00Z'
To-Date-Time:
name: to_date_time
in: query
required: false
description: 'The end date for the requested period. Pattern: YYYY-MM-DDTHH:mm:ssZ'
schema:
type: string
title: to_date_time
format: date-time
example: '2024-03-17T10:30:00Z'
From-Date:
name: from_date
in: query
required: false
description: 'The start date for the requested period. Pattern: YYYY-MM-DD'
schema:
type: string
title: from_date
format: date
example: '2024-03-17'
To-Date:
name: to_date
in: query
required: false
description: 'The end date for the requested period. Pattern: YYYY-MM-DD'
schema:
type: string
title: to_date
format: date
example: '2024-03-17'
Payment-Type:
name: payment_type
in: query
required: false
description: 'Transaction type filter. Supported values: INBOUND, PAYOUT.'
schema:
type: array
title: payment_type
items:
type: string
enum:
- INBOUND
- PAYOUT
- WITHDRAW
Reporting-Status:
name: status
in: query
required: false
description: 'Transaction status filter. Supported values: PENDING, SUCCESS, REJECTED.'
schema:
type: array
title: status
items:
type: string
enum:
- PENDING
- SUCCESS
- REJECTED
Rfi-Id:
name: rfi_id
in: query
required: false
description: RFI unique id.
schema:
type: string
title: rfi_id
minLength: 1
maxLength: 128
Type:
name: type
in: query
required: false
description: List of RFI types. Currently supports KYC, RECIPIENT.
schema:
type: string
title: type
minLength: 1
maxLength: 64
Rfi-Status:
name: status
in: query
required: false
description: List of RFI status values to filter by.
schema:
type: string
title: status
minLength: 1
maxLength: 64
Operation:
name: Operation
in: header
required: true
description: Operation to indicate which functionality to be invoked.
schema:
type: string
title: Operation
enum:
- SAVE
- SUBMIT
example: SAVE
Wallet-Payment:
name: Wallet-Payment
in: header
required: true
description: Indicates whether this is a wallet payment. Y or N.
schema:
type: string
title: Wallet-Payment
enum:
- 'Y'
- 'N'
example: 'N'
schemas:
Gateway-Error-Response:
type: object
title: GatewayErrorResponse
required:
- httpCode
- httpMessage
- moreInformation
properties:
httpCode:
type: string
maxLength: 3
description: Numeric HTTP Staus code
title: httpCode
httpMessage:
type: string
maxLength: 128
description: HTTP error message
title: httpMessage
example: Bad Request
moreInformation:
type: string
maxLength: 128
description: HTTP error message
title: moreInformation
example: please provide valid value for request
Service-Error-Response:
title: ServiceErrorResponse
type: object
required:
- ref_id
- error_details
properties:
ref_id:
type: string
maxLength: 120
description: Unique ID for the Transaction
title: ref_id
example: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
error_details:
type: array
description: List of error details
title: error_details
items:
$ref: '#/components/schemas/Error-Detail'
Error-Detail:
type: object
title: ErrorDetail
properties:
issue:
type: string
minLength: 1
maxLength: 200
description: more details about the issue
title: issue
example: property emailAddress is mandatory and it cannot be empty
action:
type: string
maxLength: 350
description: corrective action to be taken to resolve above issue
title: action
example: please provide valid value for property emailAddress
code:
type: string
minLength: 1
maxLength: 64
description: unique code representing the issue
title: code
example: VC00010
Merchant-Onboarding-Request:
title: MerchantOnboardingRequest
description: Request parameters for Merchant Onboarding Request.
allOf:
- $ref: '#/components/schemas/Common-Merchant-Onboarding-Request'
- type: object
required:
- partner_user_id
properties:
partner_user_id:
$ref: '#/components/schemas/Partner-User-Id'
Get-Merchant-Onboarding:
title: GetMerchantOnboarding
description: Response for Get Merchant Onboarding.
allOf:
- $ref: '#/components/schemas/Common-Merchant-Onboarding-Request'
- type: object
required:
- merchant_id
properties:
merchant_id:
$ref: '#/components/schemas/Merchant-Id'
Common-Merchant-Onboarding-Request:
title: CommonMerchantOnboardingRequest
description: Request parameters for Merchant Onboarding Request.
type: object
required:
- contact_number
- contact_prefix
- email
properties:
contact_number:
type: string
description: Contact number of the merchant.
title: contact number
minLength: 1
maxLength: 32
example: '9234567890'
contact_prefix:
type: string
description: Country code of the contact number.
title: contact_prefix
minLength: 1
maxLength: 32
example: '+91'
email:
type: string
description: >-
The email address of the merchant. It should always be in lower
case.
title: email
minLength: 1
maxLength: 64
example: abc@yahoo.com
Merchant-Onboarding-Response:
title: MerchantOnboardingResponse
description: Response parameters for Merchant Onboarding Response.
type: object
properties:
merchant_id:
$ref: '#/components/schemas/Merchant-Id'
status_details:
$ref: '#/components/schemas/Status-Details'
Status-Details:
title: StatusDetails
description: Status Details.
type: object
properties:
status:
$ref: '#/components/schemas/Status'
message:
$ref: '#/components/schemas/Message'
File-Upload-Response:
title: FileUploadResponse
description: Response parameters for file upload.
type: object
properties:
file_id:
$ref: '#/components/schemas/File-Id'
created_time:
$ref: '#/components/schemas/Created-Time'
status_details:
$ref: '#/components/schemas/Status-Details'
File-Download-Response:
title: FileDownloadResponse
type: array
description: Response for file download.
items:
$ref: '#/components/schemas/File-Download'
File-Download:
title: FileDownload
type: object
description: File download details.
properties:
file_id:
$ref: '#/components/schemas/File-Id'
file_download_link:
type: string
title: file_download_link
description: >-
File link for downloading the file. The link is valid for 15 minutes
and can be used only once.
minLength: 1
maxLength: 256
example: https://pingpongx.com/
File-Id:
type: string
description: Unique identifier for the document uploaded.
title: file_id
minLength: 1
maxLength: 128
example: '112213'
Created-Time:
type: string
format: date-time
description: Date and time of the file created. Pattern YYYY-MM-DDTHH:mm:ssZ
title: created_time
example: '2026-01-06T10:56:25Z'
Merchant-Id:
type: string
description: >-
Unique identifier generated by Citi for each seller. Seller to use this
id for the further functional calls.
title: merchant_id
minLength: 1
maxLength: 36
example: ec689822-9864-4c4d-9d68-222467627901
Partner-User-Id:
type: string
description: Partner user identifier for seller from your system.
title: partner_user_id
minLength: 1
maxLength: 50
example: '1323436'
Status:
type: string
description: Status of the request.
title: status
minLength: 1
maxLength: 64
Message:
type: string
description: Description of the status.
title: message
minLength: 1
maxLength: 500
example: Request is in-progress
Business-Address:
title: BusinessAddress
type: object
description: Address information for company.
properties:
street_name:
type: string
title: street_name
minLength: 1
maxLength: 200
description: Street name. Required for CHINA and HONGKONG.
example: Schillerstrasse 23
postal_code:
type: string
title: postal_code
minLength: 1
maxLength: 16
description: Postal code or ZIP code. Required for CHINA and HONGKONG.
example: '999077'
city:
type: string
title: city
minLength: 1
maxLength: 200
description: City name. Required for CHINA and HONGKONG.
example: Ras Al Khaimah
district:
type: string
title: district
minLength: 1
maxLength: 200
description: District name. Required for CHINA and HONGKONG.
example: district1111
state:
type: string
title: state
minLength: 1
maxLength: 200
description: State or province name. Required for CHINA and HONGKONG.
example: Ras al Khaymah
Document:
title: Document
type: object
description: >-
Document information for KYC validation including document type,
sub-type, and file reference.
required:
- type
properties:
type:
type: string
title: type
description: >-
Type of identity document (ID).
certificate_of_registration is
applicable for CHINA.
certificate_of_incorporation and
business_registration are applicable for HONGKONG.
enum:
- CERTIFICATE_OF_REGISTRATION
- CERTIFICATE_OF_INCORPORATION
- BUSINESS_REGISTRATION
- SHARE_STRUCTURE
- COMPANY_CONSTITUTION_OR_ANNUAL_REPORT
- ARTICLE_OF_ASSOCIATION
- UBO_DECLARATION
- PARTNERSHIP_MINUTES_OF_MEETING
- PARTNERSHIP_DEED
- CERTIFICATE_OF_INCUMBENCY
- INDONESIA_MINISTRY_OFFICIAL_APPROVAL_PROOF
- OFFICE_PHOTO
- PROOF_OF_ADDRESS
- BANK_ACCOUNT_PROOF
- BUSINESS_URL_OWNERSHIP
example: CERTIFICATE_OF_REGISTRATION
sub_type:
type: string
title: sub_type
description: Applicable only if the type is certificate_of_registration.
enum:
- ACRA
- GST
- MSME
- CERTIFICATE_OF_REGISTRATION
example: ACRA
number:
type: string
title: number
minLength: 1
maxLength: 128
description: >-
Document ID number.
required if type is
certificate_of_registration for CHINA.
required if type are
certificate_of_incorporation and business_registration for HONGKONG.
example: DE123456789
file_id:
$ref: '#/components/schemas/File-Id'
Person-Document:
title: PersonDocument
type: object
description: Document information for business person KYC validation.
required:
- type
- sub_type
properties:
type:
type: string
title: type
description: >-
Type of identity document (ID). Provide details for one primary
identity document (CHINESE_RESIDENT_IDENTITY_CARD,
NATIONAL_OR_STATE_ID, PASSPORT, DRIVERS_LICENSE, RESIDENCE_PERMIT,
TAX_ID, PROOF_OF_AGE_CARD, MY_NUMBER_CARD, MAINLAND_TRAVEL_PERMIT),
optionally supplemented by AUTHORISED_LETTER, PROOF_OF_ADDRESS, or
HAND_HOLD_PHOTO if required.
AUTHORISED_LETTER is required if
the role is AUTHORISED_PERSON
NATIONAL_OR_STATE_ID, PASSPORT,
RESIDENCE_PERMIT, MAINLAND_TRAVEL_PERMIT are applicable for CHINA.
NATIONAL_OR_STATE_ID, PASSPORT, RESIDENCE_PERMIT,
CHINESE_RESIDENT_IDENTITY_CARD, MAINLAND_TRAVEL_PERMIT are
applicable for HONGHONG.
enum:
- CHINESE_RESIDENT_IDENTITY_CARD
- NATIONAL_OR_STATE_ID
- PASSPORT
- DRIVERS_LICENSE
- RESIDENCE_PERMIT
- TAX_ID
- PROOF_OF_AGE_CARD
- MY_NUMBER_CARD
- MAINLAND_TRAVEL_PERMIT
- AUTHORISED_LETTER
- PROOF_OF_ADDRESS
- HAND_HOLD_PHOTO
example: NATIONAL_OR_STATE_ID
sub_type:
type: string
title: sub_type
description: >-
Applicable for all id type other than PASSPORT. Front and Back both
sub_type is applicable for CN and HK. When BACK is used, number,
expiry_date, issue_date, issuing_authority are not required.
enum:
- FRONT
- BACK
example: FRONT
number:
type: string
title: number
minLength: 1
maxLength: 128
description: Document ID number. Required for CHINA and HONGKONG.
example: ID123456789
expiry_date:
allOf:
- $ref: '#/components/schemas/Common-Date'
title: expiry_date
description: >-
The expiry date of the ID document; format yyyy-mm-dd. Fill in
9999-12-31 if there is no expiry date. Required for CHINA and
HONGKONG.
issue_date:
allOf:
- $ref: '#/components/schemas/Common-Date'
title: issue_date
description: >-
Issuing date of the ID document; format yyyy-mm-dd. Required for
CHINA and HONGKONG.
issuing_authority:
type: string
title: issuing_authority
minLength: 1
maxLength: 2048
description: >-
Issuing authority of merchant's identity document. Required for
CHINA and HONGKONG.
example: Government of China
file_id:
$ref: '#/components/schemas/File-Id'
Business-Person-Address:
title: BusinessPersonAddress
description: Business person address information.
allOf:
- $ref: '#/components/schemas/Business-Address'
- type: object
title: Business-Person-Address
properties:
country_code:
allOf:
- $ref: '#/components/schemas/Country-Code'
title: country_code
description: Country code. Required for CHINA and HONGKONG.
Country-Code:
type: string
title: country_code
pattern: ^[A-Z]{2,2}$
description: Country code.
example: CN
Common-Date:
type: string
title: date
format: date
description: Date in ISO 8601 (YYYY-MM-DD).
example: '1975-03-07'
Birth-Details:
title: BirthDetails
type: object
description: Birth information of the business person.
properties:
date:
allOf:
- $ref: '#/components/schemas/Common-Date'
title: date
description: ISO 8601 (YYYY-MM-DD), birth_date is required for CN and HK.
country_code:
allOf:
- $ref: '#/components/schemas/Country-Code'
title: country_code
description: Country code.
state:
type: string
title: state
minLength: 1
maxLength: 2048
description: State (province of birth).
example: beijing
Personal-Details:
title: Personal-Details
type: object
description: This section contains the name details.
properties:
first_name:
type: string
title: first_name
minLength: 1
maxLength: 64
description: Business person's first name in English. Required for CN and HK.
example: Hongbo
first_name_in_local_language:
type: string
title: first_name_in_local_language
minLength: 1
maxLength: 64
description: >-
Business person's first name in local language. Required for CN and
HK.
example: first name
middle_name:
type: string
title: middle_name
minLength: 1
maxLength: 64
description: Business person's middle name in English. Optional for CN and HK.
example: s
middle_name_in_local_language:
type: string
title: middle_name_in_local_language
minLength: 1
maxLength: 64
description: >-
Business person's middle name in local language. Optional for CN and
HK.
example: middle name
last_name:
type: string
title: last_name
minLength: 1
maxLength: 64
description: Business person's last name in English. Required for CN and HK.
example: Lin
last_name_in_local_language:
type: string
title: last_name_in_local_language
minLength: 1
maxLength: 64
description: >-
Business person's full name in local language. Required for CN and
HK.
example: last name
Business-Person:
title: BusinessPerson
description: Business person details for KYC certification.
allOf:
- $ref: '#/components/schemas/Personal-Details'
- type: object
properties:
role:
type: string
title: role
description: >-
Role of business person. Required for both CHINA and HONGKONG.
UBO, DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP,
AGENT_OR_AUTHORISED_PERSON are applicable for CHINA.
UBO,
DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP, AGENT_OR_AUTHORISED_PERSON
are applicable for HONGKONG.
For the limitation on the
number of business persons-
UBO - 4 maximum across all
regions (as UBO is defined as shareholding above 25%).
Legal rep/Director - 1 for CN (only one legal rep per CN law)
and up to 25 directors for HK.
Agent - 1, as there can only
be 1 agent.
enum:
- OWNER_OR_OPERATOR
- PARTNER
- UBO
- DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP
- AGENT_OR_AUTHORISED_PERSON
example: AGENT_OR_AUTHORISED_PERSON
alias:
type: string
title: alias
minLength: 1
maxLength: 2048
description: Business person's alias name.
example: Hongbo
nationality:
type: string
title: nationality
description: Business person's nationality. Required for CHINA and HONGKONG.
example: CN
pattern: ^[A-Z]{2,2}$
gender:
type: string
title: gender
description: Business person's gender.
enum:
- MALE
- FEMALE
example: MALE
birth_details:
$ref: '#/components/schemas/Birth-Details'
address:
$ref: '#/components/schemas/Business-Person-Address'
tax_id_number:
type: string
title: tax_id_number
minLength: 1
maxLength: 128
description: Tax id number.
example: tax123456
business_title:
type: string
title: business_title
minLength: 1
maxLength: 2048
description: Business title.
example: Director
documents:
type: array
description: List of documents
title: documents
items:
$ref: '#/components/schemas/Person-Document'
Business:
title: Business
type: object
description: Detailed information of the business for certification.
required:
- name
properties:
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: >-
The full legal name of the business in English. Required for CN
and HK.
example: payment service provider
name_in_local_language:
type: string
title: name_in_local_language
minLength: 1
maxLength: 128
description: >-
The full legal name of the business in the local language. Required
for CN and HK.
example: payment service provider
establishment_date:
allOf:
- $ref: '#/components/schemas/Common-Date'
title: establishment_date
description: Company establishment date. Required for CN and HK.
license_expiry_date:
allOf:
- $ref: '#/components/schemas/Common-Date'
title: license_expiry_date
description: >-
Expiry date of company license; format yyyy-mm-dd. Fill in
9999-12-31 for a long-term license. Required for CN. For HK, this is
expiry date of business registration.
address:
$ref: '#/components/schemas/Business-Address'
products_and_services_category:
type: string
title: products_and_services_category
description: Products and services category. Required for CN and HK.
example: KC02001008
minLength: 1
maxLength: 20
tax_id_type:
type: string
title: tax_id_type
description: Tax id type.
enum:
- EIN
- SSN
- VAT
- TIN
- UTR
example: VAT
tax_id_number:
type: string
title: tax_id_number
minLength: 1
maxLength: 128
description: Tax id number.
example: tax_id_number1111
account_usage:
type: array
title: account_usage
description: List of account usage. Required for CN and HK.
items:
$ref: '#/components/schemas/Account-Usage'
minItems: 1
maxItems: 25
description:
type: string
title: description
minLength: 1
maxLength: 2048
description: >-
Description of the business. This is one of the three ways of
proving the business.
example: Selling products or purchasing raw materials on online platforms
website:
type: string
title: website
minLength: 1
maxLength: 2048
description: Website URL. This is one of the three ways of proving the business.
example: http://www.company.cn
business_proof_file_id:
allOf:
- $ref: '#/components/schemas/File-Id'
title: business_proof_file_id
description: File ID for a screenshot of the business website/dashboards.
example: N1234567891011121314151622
documents:
type: array
title: documents
description: List of documents.
items:
$ref: '#/components/schemas/Document'
business_persons:
type: array
title: business_persons
description: List of business person.
items:
$ref: '#/components/schemas/Business-Person'
Account-Usage:
type: string
title: account_usage
description: >-
Description of merchant's business purpose of using PSP account.
Required for CN and HK.
example: ONLINE_MARKETPLACE_TRADING
Certification-Request:
title: CertificationRequest
description: >-
Request body for submitting certification information for KYC
verification.
allOf:
- $ref: '#/components/schemas/Certification-Common-Details'
- type: object
title: Certification-Request
required:
- country_code
- merchant_ack
- business
Certification-Common-Details:
title: CertificationCommonDetails
type: object
description: Certification details.
properties:
country_code:
allOf:
- $ref: '#/components/schemas/Country-Code'
title: country_code
description: Country code.
merchant_ack:
type: string
title: merchant_ack
description: >-
Has the merchant signed the payment service provider service terms?
YES or NO.
enum:
- 'YES'
- 'NO'
example: 'YES'
business:
$ref: '#/components/schemas/Business'
Webhook-Certification:
title: WebhookCertification
description: Notification for certification status updates.
allOf:
- $ref: '#/components/schemas/Common-Error-Response'
- type: object
properties:
business_name:
type: string
title: business_name
minLength: 1
maxLength: 256
description: Business name in English.
example: business name
business_name_in_local_language:
type: string
title: business_name_in_local_language
minLength: 1
maxLength: 64
description: Business name in local language.
example: business name in local
Get-Certification-Response:
title: GetCertificationResponse
description: >-
Response body for retrieving certification details including KYC status
and business information.
allOf:
- $ref: '#/components/schemas/Certification-Common-Details'
- type: object
title: Get-Certification-Response
properties:
status:
allOf:
- $ref: '#/components/schemas/Status'
title: status
description: >-
The status of the certification. Allowed values PENDING_SAVED,
PENDING_SUBMITTED, APPROVED, DECLINED, RFI_PENDING.
message:
type: string
title: message
minLength: 1
maxLength: 500
description: Description of certification status.
example: KYC approved
merchant_type:
$ref: '#/components/schemas/Merchant-Type'
product_code:
type: string
title: product_code
description: Product code. Currently supports PAYMENT_CORE and ACQ_ONLINE.
minLength: 1
maxLength: 15
example: PAYMENT_CORE
Wallet-Activation-Request:
title: WalletActivationRequest
type: object
description: Notification for wallet activation status update.
required:
- currency_code
- bank_country_code
properties:
currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: currency_code
description: The currency code for the virtual account.
example: USD
bank_country_code:
allOf:
- $ref: '#/components/schemas/Country-Code'
title: bank_country_code
description: The country code of the bank issuing the virtual account.
Sync-Response:
title: SyncResponse
type: object
description: Acknowledgement.
properties:
status_details:
$ref: '#/components/schemas/Status-Details'
Virtual-Account:
title: VirtualAccount
type: object
description: This field contains the detailed information of account.
properties:
type:
type: string
title: type
description: Account type.
enum:
- SAVINGS
- CURRENT
- CHECKING
example: CHECKING
iban:
type: string
title: iban
description: EU international bank account number.
minLength: 1
maxLength: 32
example: SE1498203030437006071356
holder_name:
type: string
title: holder_name
description: >-
Account holder's name. Normally equal to your account name. Note
that some banks may return payment service provider in this field.
minLength: 1
maxLength: 256
example: Carol Parisian
currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: currency_code
description: Account currency code.
example: HNL
Bank:
title: Bank
type: object
description: This field contains the detailed information of bank.
properties:
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: Bank name.
minLength: 1
maxLength: 255
example: CITI Bank HongKong Branch
code:
type: string
title: code
description: Domestic bank code in the bank_location.
minLength: 1
maxLength: 32
example: '37'
branch_number:
type: string
title: branch_number
description: Domestic branch code/ associate bank number in the bank_location.
minLength: 1
maxLength: 32
example: '690'
city:
type: string
title: city
description: The city where the bank is located.
minLength: 1
maxLength: 128
example: South Devyn
address_line:
type: string
title: address_line
description: The bank's detailed address.
minLength: 1
maxLength: 256
example: Apt. 883
postal_code:
type: string
title: postal_code
description: Bank's postal or ZIP code.
minLength: 1
maxLength: 16
example: '605826'
country_code:
allOf:
- $ref: '#/components/schemas/Country-Code'
title: country_code
description: Country code.
routing_number:
type: string
title: routing_number
description: North American bank code.
minLength: 1
maxLength: 64
example: '687869237'
swift_code:
type: string
title: swift_code
description: SWIFT code.
minLength: 1
maxLength: 64
example: BETFSJGNJ8F
sort_code:
type: string
title: sort_code
description: UK bank sort code (6 digits).
minLength: 1
maxLength: 32
example: '430391'
Webhook-Wallet-Activation:
title: WebhookWalletActivation
description: Wallet activation notification for the status update.
allOf:
- $ref: '#/components/schemas/Wallet-Activation'
- $ref: '#/components/schemas/Common-Error-Response'
- type: object
title: Webhook-Wallet-Activation
Webhook-Error-Response:
title: WebhookErrorResponse
description: Details of error in the request.
allOf:
- $ref: '#/components/schemas/Common-Error-Response'
- type: object
properties:
error_details:
type: array
description: List of error details
title: error_details
items:
$ref: '#/components/schemas/Error-Detail'
Common-Error-Response:
title: CommonErrorResponse
description: Details of error in the request.
type: object
properties:
merchant_id:
$ref: '#/components/schemas/Merchant-Id'
status:
allOf:
- $ref: '#/components/schemas/Status'
description: >-
Status description.
Certification Webhook - Allowed values are
APPROVED, DECLINED, RFI_PENDING.
Wallet Activation Webhook -
Allowed values are AVAILABLE - account is available to be used;
DECLINED - account application rejected; SUSPENDED - account is
frozen; CLOSED - account is no longer available.
Link Account
Webhook - Allowed values are AVAILABLE and DECLINED
Payment
Webhook - Allowed values are SUCCESS, REJECTED.
Inbound Webhook
- Allowed values is SUCCESS.
Transaction Reporting - PENDING,
SUCCESS, REJECTED.
message:
$ref: '#/components/schemas/Message'
Virtual-Account-Id:
type: string
title: Virtual-Account-Id
description: Account ID for a specific virtual account.
minLength: 1
maxLength: 36
example: R200801012359590001
Wallet-Activation:
title: WalletActivation
type: object
description: >-
Response body containing wallet activation details and virtual account
information.
properties:
virtual_account_id:
$ref: '#/components/schemas/Virtual-Account-Id'
virtual_account_number:
type: string
title: virtual_account_number
description: Bank account number.
minLength: 1
maxLength: 64
example: '38879371'
account:
$ref: '#/components/schemas/Virtual-Account'
bank:
$ref: '#/components/schemas/Bank'
Get-Wallet-Activation:
title: GetWalletActivation
description: >-
Response body containing wallet activation details and virtual account
information.
allOf:
- $ref: '#/components/schemas/Wallet-Activation'
- type: object
properties:
status:
allOf:
- $ref: '#/components/schemas/Status'
title: status
description: >-
The status of wallet activation. PENDING - account is pending;
AVAILABLE - account is available to be used; DECLINED - account
application rejected; SUSPENDED - account is frozen; CLOSED -
account is no longer available.
message:
$ref: '#/components/schemas/Message'
Get-Wallet-Activation-Response:
title: GetWalletActivationResponse
description: Response body containing wallet and virtual account information.
type: array
items:
$ref: '#/components/schemas/Get-Wallet-Activation'
Get-Wallet-Balances:
title: GetWalletBalances
type: array
description: Response body containing wallet balance information.
items:
$ref: '#/components/schemas/Wallet-Balance-Item'
Wallet-Balance-Item:
title: WalletBalanceItem
type: object
description: Balance information for a single account.
properties:
virtual_account_id:
$ref: '#/components/schemas/Virtual-Account-Id'
account_type:
type: string
title: account_type
description: Either BALANCE_ACCOUNT or TEMP_ACCOUNT.
enum:
- BALANCE_ACCOUNT
- TEMP_ACCOUNT
example: BALANCE_ACCOUNT
currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: currency_code
description: Currency of the balance.
example: USD
available_amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: available_amount
description: Balance of the account and currency.
Amount:
type: number
title: amount
description: Amount in currency.
minimum: 0.01
maximum: 10000000000000
example: 1000
Currency-Code:
type: string
title: currency_code
description: The currency code in the transaction.
pattern: ^[A-Z]{3}$
example: USD
Link-Account-Request:
title: LinkAccountRequest
type: object
description: Request body for linking an external account for payments.
required:
- creditor_account
- creditor_bank
- creditor
properties:
creditor_account:
$ref: '#/components/schemas/Creditor-Account'
creditor_bank:
$ref: '#/components/schemas/Creditor-Bank'
creditor:
$ref: '#/components/schemas/Creditor'
file_id:
$ref: '#/components/schemas/File-Id'
Creditor-Id:
type: string
title: creditor_id
description: The unique creditor identifier assigned by payment service provider.
minLength: 1
maxLength: 36
example: R202501080950209789
Get-Link-Account-Response:
title: GetLinkAccountResponse
description: Response body containing linked account details.
type: array
items:
$ref: '#/components/schemas/Creditor-Detail'
Creditor-Detail:
title: CreditorDetail
type: object
description: Response body containing creditor's details.
properties:
creditor_id:
$ref: '#/components/schemas/Creditor-Id'
status:
allOf:
- $ref: '#/components/schemas/Status'
title: status
description: The status of creditor validation. PENDING; AVAILABLE; DECLINED
message:
$ref: '#/components/schemas/Message'
created_time:
$ref: '#/components/schemas/Created-Time'
creditor_account:
$ref: '#/components/schemas/Get-Creditor-Account'
creditor_bank:
$ref: '#/components/schemas/Get-Creditor-Bank'
creditor:
$ref: '#/components/schemas/Get-Creditor'
file_id:
$ref: '#/components/schemas/File-Id'
Webhook-Link-Account:
title: WebhookLinkAccount
description: Notification for Link account for the status update.
allOf:
- $ref: '#/components/schemas/Common-Error-Response'
- type: object
title: Webhook-Link-Account
properties:
creditor_id:
$ref: '#/components/schemas/Creditor-Id'
Get-Creditor-Account:
title: GetCreditorAccount
description: This section contains the details information of bank.
allOf:
- $ref: '#/components/schemas/Creditor-Account-Details'
- type: object
title: Get-Creditor-Account
properties:
type:
type: string
title: type
description: Type of the bank.
minLength: 1
maxLength: 64
example: CHECKING
Creditor-Account:
title: CreditorAccount
description: Creditor Account.
allOf:
- $ref: '#/components/schemas/Creditor-Account-Details'
- type: object
title: Creditor-Account'
required:
- holder_type
- number
- name
- currency_code
Creditor-Account-Details:
title: CreditorAccountDetails
type: object
description: This section contains the details information of account.
properties:
holder_type:
type: string
title: holder_type
description: The type of account holder.
enum:
- PERSONAL
- COMPANY
example: PERSONAL
holder_contact_number:
type: string
title: holder_contact_number
description: The full contact number, including the country code if mobile.
minLength: 1
maxLength: 32
example: 007 3700 7457
number:
type: string
title: number
description: Unique account number.
minLength: 1
maxLength: 64
example: '703912345678'
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: Name of the account.
example: SHASHANK VIJAYSHANKAR TIWARI
currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: currency_code
description: Currency of the account (3-character ISO code).
example: INR
iban:
type: string
title: iban
description: >-
International Bank Account Number (IBAN). IBAN is not applicable for
CN and HK.
minLength: 1
maxLength: 32
example: HU58711204120061837086422231
document_type:
type: string
title: document_type
description: >-
Type of identity document (ID). One of the following 00 Chinese
national ID card 01 Chinese residence permit 02 Passport 03 ID card
of Hong Kong, Macao or Taiwan 04 Residence permit of Hong Kong,
Macao and Taiwan 05 Hong Kong and Macao travel permit 06 Other
national ID card 07 Other residence permit
enum:
- CHINESE_NATIONAL_ID_CARD
- CHINESE_RESIDENCE_PERMIT
- PASSPORT
- ID_CARD_OF_HONGKONG_MACAO_OR_TAIWAN
- RESIDENCE_PERMIT_OF_HONGKONG_MACAO_AND_TAIWAN
- HONGKONG_AND_MACAO_TRAVEL_PERMIT
- OTHER_NATIONAL_ID_CARD
- OTHER_RESIDENCE_PERMIT
example: CHINESE_RESIDENCE_PERMIT
document_number:
type: string
title: document_number
description: Account holder's ID number.
minLength: 1
maxLength: 64
example: CS8899966
Get-Creditor-Bank:
title: GetCreditorBank
description: This section contains the details information of bank.
allOf:
- $ref: '#/components/schemas/Creditor-Bank-Details'
- type: object
title: Get-Creditor-Bank
properties:
type:
type: string
title: type
description: Type of the bank.
minLength: 1
maxLength: 64
example: RECIPIENT BANK
address:
$ref: '#/components/schemas/Address-Details'
Creditor-Bank:
title: CreditorBank
description: Creditor Bank.
allOf:
- $ref: '#/components/schemas/Creditor-Bank-Details'
- type: object
title: Creditor-Bank
required:
- name
- address
properties:
address:
$ref: '#/components/schemas/Address'
Creditor-Bank-Details:
title: CreditorBankDetails
type: object
description: This section contains the details information of bank.
properties:
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: Name of the bank.
minLength: 1
maxLength: 256
example: BANK OF BARODA
code:
type: string
title: code
description: Bank code.
minLength: 1
maxLength: 32
example: '6'
branch_name:
type: string
title: branch_name
description: Branch name where the account is held.
minLength: 1
maxLength: 128
example: THANE BRANCH
branch_number:
type: string
title: branch_number
description: Branch code where the account is held.
minLength: 1
maxLength: 32
example: '391'
swift_code:
type: string
title: swift_code
description: SWIFT BIC (Bank Identifier Code).
minLength: 1
maxLength: 64
example: CITIINHFXXX
routing_number:
type: string
title: routing_number
description: Routing code.
minLength: 1
maxLength: 64
example: '6391'
ifsc_code:
type: string
title: ifsc_code
description: Indian Financial System Code (IFSC).
minLength: 1
maxLength: 64
example: HDFC0000001
sort_code:
type: string
title: sort_code
description: Sort code.
minLength: 1
maxLength: 32
example: '87'
Address:
title: Address
description: Address/
allOf:
- $ref: '#/components/schemas/Address-Details'
- type: object
title: Address-Details
required:
- country_code
- city
- state
Address-Details:
title: AddressDetails
type: object
description: Address information for the bank.
properties:
city:
type: string
title: city
description: City.
minLength: 1
maxLength: 128
example: THANE
state:
type: string
title: state
description: State.
minLength: 1
maxLength: 128
example: MAHARASHTRA
country_code:
allOf:
- $ref: '#/components/schemas/Country-Code'
title: country_code
description: Country code.
address_line:
type: string
title: address_line
description: Detailed address of the bank.
minLength: 1
maxLength: 256
example: SUMAN HEIGHTS LODHA HERITAGR NAVNEET NAGAR MAHARASHTRA THANE INDIA
Creditor:
title: Creditor
description: This section contains the details information of creditor.
allOf:
- $ref: '#/components/schemas/Common-Creditor'
- type: object
title: Common-Creditor
required:
- type
- name
- address
properties:
creditor_partner_user_id:
$ref: '#/components/schemas/Partner-User-Id'
address:
$ref: '#/components/schemas/Creditor-Address'
Get-Creditor:
title: GetCreditor
description: This section contains the details information of creditor.
allOf:
- $ref: '#/components/schemas/Common-Creditor'
- type: object
title: Get-Creditor
properties:
address:
$ref: '#/components/schemas/Creditor-Address-Details'
Common-Creditor:
title: CommonCreditor
type: object
description: This section contains the details information of creditor.
properties:
type:
type: string
title: type
description: Type of creditor.
enum:
- '00'
example: '00'
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: Name of the account.
example: SHASHANK VIJAYSHANKAR TIWARI
contact_number:
type: string
title: contact_number
description: Full contact number.
minLength: 1
maxLength: 32
example: '9876543210'
contact_prefix:
type: string
title: contact_prefix
description: International telephone area code.
minLength: 1
maxLength: 32
example: '91'
email:
type: string
title: email
description: Email address of the merchant.
minLength: 1
maxLength: 32
example: abc@pp.com
Partial-Address:
title: PartialAddress
description: Address information for the creditor.
type: object
properties:
street_name:
type: string
title: street_name
description: Street name.
minLength: 1
maxLength: 128
example: ROYAL STREET
postal_code:
type: string
title: postal_code
description: Postal code.
minLength: 1
maxLength: 16
example: '5110'
Creditor-Address:
title: CreditorAddress
description: Address information for the creditor.
allOf:
- $ref: '#/components/schemas/Address-Details'
- $ref: '#/components/schemas/Partial-Address'
- type: object
title: Creditor-Address
required:
- country_code
- city
- state
Creditor-Address-Details:
title: CreditorAddressDetails
description: Address information for the creditor.
allOf:
- $ref: '#/components/schemas/Address-Details'
- $ref: '#/components/schemas/Partial-Address'
- type: object
title: Creditor-Address-Details
Multiple-Currency-Amount:
title: FxQuery
type: object
properties:
buy_currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: buy_currency_code
description: The currency that the client is buying.
example: CNH
buy_amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: buy_amount
description: >-
The amount of buy_currency for the transaction. (You ONLY need to
define one amount, either buy_amount or sell_amount in a request.)
example: 100.11
sell_currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: sell_currency_code
description: The currency that the client is selling.
example: USD
sell_amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: sell_amount
description: >-
The amount of sell_currency for the transaction. (You ONLY need to
define one amount, either buy_amount or sell_amount in a request.)
example: 80.1
Fx-Query-Request:
title: FxQueryRequest
allOf:
- $ref: '#/components/schemas/Multiple-Currency-Amount'
- type: object
title: Fx-Query-Request
required:
- buy_currency_code
- sell_currency_code
- reference_id
- seller_markup
properties:
seller_markup:
type: string
title: seller_markup
description: Seller markup consists of country code + markup.
example: CN-150
reference_id:
$ref: '#/components/schemas/Reference-Id'
Reference-Id:
type: string
title: reference_id
description: Unique identifier for this request from your system.
example: '12456'
minLength: 1
maxLength: 120
Fx-Rate-Id:
type: string
title: fx_rate_id
description: >-
When you request a guaranteed quote of Instant FX and Reserved FX, the
Citi will return a `fx_rate_id`, which is the unique ID only for
guaranteed `fx_indi_rate. fx_rate_id is mandatory for other than USD
to USD transfer.
minLength: 1
maxLength: 64
example: '16098876465273400000'
Fx-Rate:
type: number
title: fx_rate
description: >-
The indicative FX rate which is for reference only. The number indicates
how much units of buy_currency you can get from one unit of
sell_currency.
Fx-Query-Response:
title: FxQueryResponse
allOf:
- $ref: '#/components/schemas/Multiple-Currency-Amount'
- type: object
title: Fx-Query-Response
required:
- buy_currency_code
- buy_amount
- sell_currency_code
- sell_amount
- fx_rate
- reference_id
properties:
fx_rate_id:
$ref: '#/components/schemas/Fx-Rate-Id'
fx_rate:
$ref: '#/components/schemas/Fx-Rate'
value_date:
allOf:
- $ref: '#/components/schemas/Common-Date'
title: value_date
description: >-
Settlement date of the FX transaction (yyyy-MM-dd, not required
for Instant FX transactions).
expiry_time:
allOf:
- $ref: '#/components/schemas/Created-Time'
title: expiry_time
description: >-
The expiration timestamp of the quote. If the transaction is not
executed, the `fx_rate_id` will expire after the date and time.
After the expiration timestamp, you should request new fx_rate
format : YYYY-MM-DDTHH:mm:ssZ).
reference_id:
$ref: '#/components/schemas/Reference-Id'
Payment-Request:
title: PaymentRequest
type: object
description: >-
Request body for creating a payment. Contains the payload with debtor,
creditor, and transaction details.
required:
- payments
properties:
message_id:
allOf:
- $ref: '#/components/schemas/Message-Id'
description: Unique identifier for bulk payments. Required for payment to wallet.
payments:
type: array
title: payments
items:
$ref: '#/components/schemas/Payment-Details'
Payment-Details:
title: PaymentDetails
type: object
description: Payment details.
required:
- payment_info
properties:
debtor:
$ref: '#/components/schemas/Payment-Debtor'
payment_info:
type: array
title: payment_info
items:
$ref: '#/components/schemas/Payment-Info-Details'
Partner-User-Reference:
title: PartnerUserReference
type: string
description: Unique reference from seller for each payment.
minLength: 1
maxLength: 35
example: PUR1234556567wegry
Transaction-Details:
title: TransactionDetails
type: object
description: Transaction details.
allOf:
- $ref: '#/components/schemas/Common-Transaction'
- type: object
title: Transaction-Details
required:
- end_to_end_id
- amount
- currency_code
properties:
partner_user_reference:
$ref: '#/components/schemas/Partner-User-Reference'
equivalent_currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: equivalent_currency_code
description: >-
The currency you use to fund the payment.
Required for
payment to external.
equivalent_amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: equivalent_amount
description: Amount in origin currency.
fx_rate_id:
allOf:
- $ref: '#/components/schemas/Fx-Rate-Id'
title: fx_rate_id
example: '3885000000000000000'
charges_type:
type: string
title: charges_type
description: Charges type.
enum:
- OUR
- SHAR
example: SHAR
purpose_code:
type: string
title: purpose_code
minLength: 1
maxLength: 50
description: >-
Payment purpose code. Required for payment to external parties.
Supported values are 1001 (Physical goods), 3003 (Logistics),
3005 (Salary), 3006 (Business/ Commission), 3007 (Family
support), 3009 (Rent), 3010 (Tax), 3011 (Property/management
fees), 3012 (Water electricity), 3016 (Patent), 3017 (Accounting
Service), 3018 (Office Expenses), 3019 (Advertising), 3021
(Transfer to Own Account), 3022 (Warehousing), 3023
(GoodsInsurance), 3024 (AttorneysFee), 3025 (StaffWelfare)
example: '1001'
file_id:
$ref: '#/components/schemas/File-Id'
payment_type:
$ref: '#/components/schemas/Payment-Type'
Method:
title: method
type: object
description: This object contains the payment method and clearing network details.
required:
- type
- method
properties:
type:
type: string
title: type
description: >-
Payment method. Required for payment to external and payment to
wallet.
payment to wallet - LOCAL should be used.
payment
to external - CROSS_BORDER.
enum:
- CROSS_BORDER
- LOCAL
example: CROSS_BORDER
method:
type: string
title: method
description: >-
ACH, IP, RTGS, DFT, SEPA, BKT, CBFT.
For payment to wallet -
value must be BKT
For payment to external - value should be
CBFT.
enum:
- ACH
- IP
- RTGS
- DFT
- SEPA
- BKT
- CBFT
example: CBFT
country_code:
allOf:
- $ref: '#/components/schemas/Country-Code'
title: country_code
description: Country code of the debtor.
Payment-Info-Details:
title: PaymentInfoDetails
type: object
description: Payment Information details.
required:
- transaction
- method
properties:
transaction:
$ref: '#/components/schemas/Transaction-Details'
creditor:
$ref: '#/components/schemas/Payment-Creditor'
method:
$ref: '#/components/schemas/Method'
Payment-Debtor:
title: Debtor
type: object
description: Information pertaining to debtor of the payment.
properties:
account:
$ref: '#/components/schemas/Account'
country_code:
allOf:
- $ref: '#/components/schemas/Country-Code'
title: country_code
description: Country code where the fund is credited.
Reporting-Debtor:
title: ReportingDebtor
description: Debtor details for reporting.
allOf:
- $ref: '#/components/schemas/Payment-Debtor'
- type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: Name of the debtor.
Reporting-Creditor:
title: ReportingCreditor
description: Crediotr details for reporting.
allOf:
- $ref: '#/components/schemas/Payment-Creditor'
- type: object
properties:
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: Name of the creditor.
Name:
type: string
title: name
minLength: 1
maxLength: 128
example: SHASHANK VIJAYSHANKAR TIWARI
Payment-Creditor:
title: Creditor
type: object
description: Information pertaining to creditor of the payment.
properties:
id:
type: string
title: id
minLength: 1
maxLength: 64
description: >-
Required when paying into a bank account. creditor_id is
returned when you call Link Account endpoint.
Required for
payment to external.
example: R202501080950209789
account:
$ref: '#/components/schemas/Account'
Account:
title: Account
type: object
description: Account details.
properties:
number:
type: string
title: number
description: Account number.
example: '456456547'
branch_code:
type: string
title: branch_code
description: Branch code which holds the account number.
example: VA202501080950209789
virtual_account_id:
allOf:
- $ref: '#/components/schemas/Virtual-Account-Id'
description: >-
virtual_account_id received when you call wallet activation
endpoint.
Required at creditor side when paying to wallet.
Required at debtor side for payment to external.
Transaction:
title: Transaction
type: object
description: Details of the transaction.
properties:
end_to_end_id:
allOf:
- $ref: '#/components/schemas/End-To-End-Id'
description: >-
Unique identifier for the payment. Required when initiating payments
(payment to wallet and payment to external).
error_details:
type: array
description: List of error details.
title: error_details
items:
$ref: '#/components/schemas/Error-Detail'
Payment-Response:
title: PaymentResponse
type: object
description: >-
Response body for payment initiation. Contains the details of the
payment.
properties:
ref_id:
type: string
minLength: 1
maxLength: 120
description: Unique ID for the Transaction.
title: ref_id
example: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
status:
$ref: '#/components/schemas/Status'
message:
$ref: '#/components/schemas/Message'
message_id:
$ref: '#/components/schemas/Message-Id'
transaction:
type: array
title: transaction
items:
$ref: '#/components/schemas/Transaction'
Webhook-Payment-Request:
title: WebhookPaymentRequest
description: Notification for payments to update the status.
allOf:
- $ref: '#/components/schemas/Webhook-Error-Response'
- type: object
properties:
message_id:
$ref: '#/components/schemas/Message-Id'
debtor:
$ref: '#/components/schemas/Payment-Debtor'
creditor:
$ref: '#/components/schemas/Payment-Creditor'
transaction:
$ref: '#/components/schemas/Webhook-Transaction'
Webhook-Transaction:
title: WebhookTransaction
type: object
description: Transaction details.
allOf:
- $ref: '#/components/schemas/Common-Transaction'
- type: object
title: Webhook-Transaction
properties:
partner_user_reference:
$ref: '#/components/schemas/Partner-User-Reference'
uetr:
$ref: '#/components/schemas/Uetr'
equivalent_currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: equivalent_currency_code
description: The currency you use to fund the payment.
equivalent_amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: equivalent_amount
description: Amount in origin currency.
charges_currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: charges_currency_code
description: Charges currency.
example: CNH
charges_amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: charges_amount
description: Charges amount.
example: 100.11
fx_rate_id:
allOf:
- $ref: '#/components/schemas/Fx-Rate-Id'
title: fx_rate_id
description: Exchange rate ID.
example: '3885000000000000000'
fx_rate:
$ref: '#/components/schemas/Fx-Rate'
created_time:
$ref: '#/components/schemas/Created-Time'
completed_time:
$ref: '#/components/schemas/Completed-Time'
Message-Id:
type: string
title: message_id
description: >-
Unique id from your system for batch. Required for Payment to Wallet
(virtual_account credit).
example: bulk123
minLength: 1
maxLength: 34
Get-Payment-Response:
title: GetPaymentResponse
type: object
description: Retrieve payments details.
properties:
message_id:
$ref: '#/components/schemas/Message-Id'
payments:
type: array
title: payments
description: A list of individual payment details.
items:
$ref: '#/components/schemas/Get-Payment-Response-Details'
Get-Payment-Response-Details:
title: GetPaymentResponseDetails
type: object
description: Get Payment Response Details.
properties:
debtor:
$ref: '#/components/schemas/Payment-Debtor'
creditor:
$ref: '#/components/schemas/Payment-Creditor'
transaction:
$ref: '#/components/schemas/Get-Transaction-Detail'
status:
$ref: '#/components/schemas/Status'
message:
$ref: '#/components/schemas/Message'
error_details:
type: array
description: List of error details.
title: error_details
items:
$ref: '#/components/schemas/Error-Detail'
Get-Transaction-Detail:
title: GetTransactionDetail
type: object
description: Retrieve transaction details.
allOf:
- $ref: '#/components/schemas/Common-Transaction'
- type: object
title: Get-Transaction-Detail
properties:
partner_user_reference:
$ref: '#/components/schemas/Partner-User-Reference'
uetr:
$ref: '#/components/schemas/Uetr'
equivalent_currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: equivalent_currency_code
description: The currency you use to fund the payout.
equivalent_amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: equivalent_amount
description: Amount in origin currency.
charges_currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: charges_currency_code
description: Charges currency code.
example: CNH
charges_amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: charges_amount
description: Charges amount.
example: 100.11
fx_rate:
$ref: '#/components/schemas/Fx-Rate'
payment_type:
$ref: '#/components/schemas/Payment-Type'
created_time:
$ref: '#/components/schemas/Created-Time'
completed_time:
$ref: '#/components/schemas/Completed-Time'
Rfi-Save-Request:
title: RfiSaveRequest
type: object
description: Request body for responding to an RFI.
required:
- rfi_id
- questions
properties:
rfi_id:
$ref: '#/components/schemas/Rfi-Id'
questions:
type: array
title: questions
description: An array of questions to respond to.
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/Questions-Request'
Rfi-Save-Response:
title: RfiSaveResponse
type: object
description: Response body for responding to an RFI.
properties:
rfi_id:
$ref: '#/components/schemas/Rfi-Id'
status:
allOf:
- $ref: '#/components/schemas/Status'
title: status
description: 'RFI status. Possible values: OPEN, CLOSED.'
example: OPEN
questions:
type: array
title: questions
description: An array of questions to respond to.
items:
$ref: '#/components/schemas/Questions-Response'
Rfi-Id:
type: string
title: rfi_id
minLength: 1
maxLength: 128
description: RFI unique id.
Questions-Request:
title: QuestionRequest
type: object
description: A question with response information for RFI submission.
required:
- question_id
- information_request
properties:
question_id:
$ref: '#/components/schemas/Question-Id'
information_request:
type: array
title: information_request
description: The information to be responded to.
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/Information-Request'
Questions-Response:
title: QuestionResponse
type: object
description: A question with response information for RFI submission.
properties:
question_id:
$ref: '#/components/schemas/Question-Id'
information_request:
type: array
title: information_request
description: The information to be responded to.
items:
$ref: '#/components/schemas/Information-Request-Response'
Question-Id:
type: string
title: question_id
minLength: 1
maxLength: 64
description: The unique id for specific question.
example: Q123456789
Information-Request:
title: InformationRequest
description: Information item that needs to be responded to in an RFI.
allOf:
- $ref: '#/components/schemas/Common-Information-Request'
- type: object
title: Information-Request
required:
- information_name
Information-Request-Response:
title: InformationRequestResponse
description: Information item that needs to be responded to in an RFI.
allOf:
- $ref: '#/components/schemas/Common-Information-Request'
- type: object
title: Information-Request-Response
Common-Information-Request:
title: CommonInformationRequest
type: object
description: Information item that needs to be responded to in an RFI.
properties:
information_name:
$ref: '#/components/schemas/Information-Name'
answer:
$ref: '#/components/schemas/Answer'
Get-Information-Request:
title: GetInformationRequest
description: Information item that needs to be responded to in an RFI.
allOf:
- $ref: '#/components/schemas/Common-Information-Request'
- type: object
title: Get-Information-Request
properties:
information_type:
$ref: '#/components/schemas/Information-Type'
Information-Type:
type: string
title: information_type
minLength: 1
maxLength: 32
description: 'Information type: text or file.'
Information-Name:
type: string
title: information_name
minLength: 1
maxLength: 64
description: Information name.
example: id_doc_front
Answer:
type: string
title: answer
minLength: 1
maxLength: 2048
description: The answer for the information request.
Rfi-Query-Response:
type: array
title: RfiQueryResponse
description: The information to be responded to.
items:
$ref: '#/components/schemas/Rfi-Query-Item'
Rfi-Query-Item:
title: Rfi-Query-Item
description: Response containing RFI list and details.
allOf:
- $ref: '#/components/schemas/Common-Rfi'
- type: object
properties:
questions:
type: array
title: questions
description: List of questions for the RFI.
items:
$ref: '#/components/schemas/Question'
Common-Rfi:
title: Common-Rfi
type: object
description: Response containing RFI list and details.
properties:
rfi_id:
$ref: '#/components/schemas/Rfi-Id'
type:
type: string
title: type
minLength: 1
maxLength: 64
description: RFI type. Currently supports KYC, RECIPIENT.
status:
allOf:
- $ref: '#/components/schemas/Status'
title: status
description: 'RFI status. Possible values: OPEN, CLOSED.'
created_time:
allOf:
- $ref: '#/components/schemas/Created-Time'
description: RFI Creation date time in ISO 8601 format.
title: created_time
expiry_time:
allOf:
- $ref: '#/components/schemas/Created-Time'
description: RFI expiration time in ISO 8601 format.
title: expiry_time
creditor_id:
allOf:
- $ref: '#/components/schemas/Creditor-Id'
title: creditor_id
description: Recipient id (use for RECIPIENT RFI type).
Question:
title: Questions
description: An individual RFI question.
allOf:
- $ref: '#/components/schemas/Common-Question'
- type: object
properties:
information_request:
type: array
title: information_request
description: The information that needs to be responded to.
items:
$ref: '#/components/schemas/Get-Information-Request'
Common-Question:
title: Common-Question
type: object
description: An individual RFI question.
properties:
question_id:
type: string
title: question_id
minLength: 1
maxLength: 64
description: The unique id for specific question.
example: Q123456789
description_code:
type: string
title: description_code
minLength: 1
maxLength: 64
description: The code for question's description.
description_english:
type: string
title: description_english
minLength: 1
maxLength: 2048
description: Question description in English.
description_chinese:
type: string
title: description_chinese
minLength: 1
maxLength: 2048
description: Question description in Chinese.
certification_source:
$ref: '#/components/schemas/Certification-Source'
Merchant-Type:
type: string
title: merchant_type
description: Type of merchant.
enum:
- INDIVIDUAL
- ENTERPRISE
Certification-Source:
title: CertificationSource
description: Information related to the KYC source.
allOf:
- $ref: '#/components/schemas/Personal-Details'
- type: object
properties:
role:
type: string
title: role
description: >-
Role of business person. Supported values are OWNER_OR_OPERATOR,
PARTNER, UBO, DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP,
AGENT_OR_AUTHORISED_PERSON.
example: AGENT_OR_AUTHORISED_PERSON
merchant_type:
$ref: '#/components/schemas/Merchant-Type'
Rfi-Submit-Request:
title: RfiSubmitRequest
type: object
description: Request body for submitting an RFI for review.
required:
- rfi_id
properties:
rfi_id:
$ref: '#/components/schemas/Rfi-Id'
Rfi-Submit-Response:
title: RfiSubmitResponse
type: object
description: Response body for RFI Submit.
properties:
status:
allOf:
- $ref: '#/components/schemas/Status'
title: status
description: 'RFI submit status. Possible values: OPEN, CLOSED.'
Pagination-Metadata:
description: >-
current_page: Current page number
total_pages: Total number of
pages available for this request
page_size: The number of records to
display per page
has_more: Any more messages or records expected
type: object
title: Pagination Metadata
properties:
current_page:
description: Current page number
type: integer
minimum: 1
maximum: 1000
example: 1
title: current_page
total_pages:
description: Total number of pages available for this request
type: integer
minimum: 1
maximum: 1000
example: 1
title: total_pages
page_size:
description: Number of records to display per page
type: integer
minimum: 1
maximum: 10000
example: 1
title: page_size
has_more:
description: Any more messages or records expected
type: boolean
example: true
title: has_more
example:
current_page: 1
total_pages: 10
page_size: 100
has_more: true
Uetr:
type: string
title: uetr
description: >-
This is a unique payment service provider ID assigned to all individual
transactions.
minLength: 1
maxLength: 36
example: '202501092053115499258'
End-To-End-Id:
type: string
title: end_to_end_id
description: >-
The unique payment request ID from your system. If the request is for
payment to wallet, this field should contain maximum 16 character and
should be in UPPER CASE.
minLength: 1
maxLength: 35
example: SM37864746
Balance:
type: number
title: opening_balance
description: Balance.
Completed-Time:
type: string
title: completed_on
format: date-time
description: The time the transaction was finished. Pattern YYYY-MM-DDTHH:mm:ssZ
example: '2026-01-06T11:00:25Z'
Balance-Transaction:
title: Balance-Transaction
type: object
description: >-
Transaction details for balance reporting including opening and closing
balances.
properties:
virtual_account_id:
$ref: '#/components/schemas/Virtual-Account-Id'
uetr:
$ref: '#/components/schemas/Uetr'
end_to_end_id:
$ref: '#/components/schemas/End-To-End-Id'
opening_balance:
allOf:
- $ref: '#/components/schemas/Balance'
title: opening_balance
description: The balance before the transaction.
example: 5000
closing_balance:
allOf:
- $ref: '#/components/schemas/Balance'
title: closing_balance
description: The balance after the transaction.
example: 4000
payment_type:
$ref: '#/components/schemas/Reporting-Payment-Type'
created_time:
allOf:
- $ref: '#/components/schemas/Created-Time'
title: created_on
description: The creation time of the transaction.
amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: amount
description: The transaction amount.
currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: currency_code
direction:
type: string
title: direction
description: Whether the transaction is a debit or credit.
example: debit
Balance-Report-Response:
title: BalanceReportResponse
type: array
items:
$ref: '#/components/schemas/Balance-Transaction'
Payment-Type:
type: string
title: payment_type
description: >-
Transaction type. WITHDRAW is applicable only if the payment is USD to
CNY to China.
enum:
- PAYOUT
- WITHDRAW
example: PAYOUT
Reporting-Payment-Type:
type: string
title: payment_type
description: Transaction type.
enum:
- INBOUND
- PAYOUT
- WITHDRAW
example: INBOUND
Common-Transaction:
title: CommonTransaction
type: object
description: Transaction details.
properties:
end_to_end_id:
$ref: '#/components/schemas/End-To-End-Id'
currency_code:
allOf:
- $ref: '#/components/schemas/Currency-Code'
title: target_currency_code
description: >-
The currency that the creditor receives. Required for payment to
wallet and payment to external.
amount:
allOf:
- $ref: '#/components/schemas/Amount'
title: target_amount
description: >-
Amount in target currency. Required for payment to wallet and
payment to external.
payment_details:
type: string
title: payment_details
description: Reference information.
minLength: 1
maxLength: 140
example: INV123
Report-Transaction:
title: ReportTransaction
description: Transaction details for reporting.
allOf:
- $ref: '#/components/schemas/Common-Error-Response'
- type: object
properties:
debtor:
$ref: '#/components/schemas/Reporting-Debtor'
creditor:
$ref: '#/components/schemas/Reporting-Creditor'
transaction:
$ref: '#/components/schemas/Report-Transaction-Detail'
Report-Transaction-Detail:
title: ReportTransactionDetails
type: object
description: Transaction details for reporting.
allOf:
- $ref: '#/components/schemas/Common-Transaction'
- $ref: '#/components/schemas/Multiple-Currency-Amount'
- type: object
properties:
uetr:
$ref: '#/components/schemas/Uetr'
fx_rate:
$ref: '#/components/schemas/Fx-Rate'
payment_type:
$ref: '#/components/schemas/Reporting-Payment-Type'
created_time:
$ref: '#/components/schemas/Created-Time'
completed_time:
$ref: '#/components/schemas/Completed-Time'
Transaction-Report-Response:
type: array
title: TransactionReportResponse
items:
$ref: '#/components/schemas/Report-Transaction'
Inbound-Payment-Notification:
type: object
title: Inbound-Payment-Notification
description: Inbound payment notification.
properties:
merchant_id:
$ref: '#/components/schemas/Merchant-Id'
debtor:
$ref: '#/components/schemas/Inbound-Debtor'
debtor_bank:
$ref: '#/components/schemas/Debtor-Bank'
creditor:
$ref: '#/components/schemas/Inbound-Creditor'
transaction:
$ref: '#/components/schemas/Inbound-Transaction'
status:
allOf:
- $ref: '#/components/schemas/Status'
description: >-
Status of the incoming payments to virtual account. Possible values:
SUCCESS, REJECTED.
message:
$ref: '#/components/schemas/Message'
inbound_type:
type: string
title: inbound_type
description: Type of inbound review.
example: INBOUND
Inbound-Debtor:
type: object
description: This section contains detailed payor information.
allOf:
- $ref: '#/components/schemas/Common-Inbound'
- type: object
title: Inbound-Debtor
properties:
country_code:
type: string
title: country_code
description: Payer's country.
minLength: 1
maxLength: 128
example: CN
Debtor-Bank:
type: object
title: Debtor-Bank
description: This section contains detailed payor bank information.
properties:
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: Bank name of the payer.
example: Citi Bank US
Common-Inbound:
type: object
title: Inbound-Common
description: This section contains Common details.
properties:
name:
allOf:
- $ref: '#/components/schemas/Name'
- description: Creditor's name.
example: Su Lin
account_number:
type: string
title: account_number
description: Account number of the VA receiving funds.
minLength: 1
maxLength: 64
example: '78945615'
address:
type: string
title: address
description: Recipient's address.
example: Schillerstrasse 23
Inbound-Creditor:
type: object
description: This section contains detailed payee information.
allOf:
- $ref: '#/components/schemas/Common-Inbound'
- type: object
title: Inbound-Creditor
Inbound-Transaction:
type: object
title: Transaction
description: This section contains detailed transaction information.
allOf:
- $ref: '#/components/schemas/Common-Transaction'
- type: object
title: Transaction-Details
properties:
uetr:
$ref: '#/components/schemas/Uetr'
RFI-Notification:
type: object
title: RFI-Notification
description: Request for Information (RFI) notification.
allOf:
- $ref: '#/components/schemas/Common-Rfi'
- type: object
required:
- merchant_id
properties:
merchant_id:
$ref: '#/components/schemas/Merchant-Id'
questions:
type: array
title: questions
description: An array of RFI questions
items:
$ref: '#/components/schemas/RFI-Question'
RFI-Question:
title: RFI-Question
description: >-
An individual RFI question with its associated information requests and
certification source.
allOf:
- $ref: '#/components/schemas/Common-Question'
- type: object
properties:
information_request:
type: array
title: information_request
description: The information need to be responded.
items:
$ref: '#/components/schemas/Information-Request-Webhook'
Information-Request-Webhook:
type: object
title: Information-Request-Webhook
description: Information that needs to be responded to for the RFI question.
properties:
information_name:
$ref: '#/components/schemas/Information-Name'
information_type:
$ref: '#/components/schemas/Information-Type'
responses:
Bad-Request:
description: Bad Request
content:
application/json:
schema:
title: Bad-Request-Response
oneOf:
- $ref: '#/components/schemas/Gateway-Error-Response'
- $ref: '#/components/schemas/Service-Error-Response'
examples:
Bad-Request-Service-Error-Example:
$ref: '#/components/examples/Bad-Request-Service-Error-Example'
Bad-Request-Gateway-Error-Example:
$ref: '#/components/examples/Bad-Request-Gateway-Error-Example'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
title: Unauthorized-Response
oneOf:
- $ref: '#/components/schemas/Service-Error-Response'
- $ref: '#/components/schemas/Gateway-Error-Response'
examples:
Unauthorized-Service-Error-Example:
$ref: '#/components/examples/Unauthorized-Service-Error-Example'
Unauthorized-Gateway-Error-Example:
$ref: '#/components/examples/Unauthorized-Gateway-Error-Example'
Internal-Server-Error:
description: Internal Server Error
content:
application/json:
schema:
title: Internal-Server-Error-Response
oneOf:
- $ref: '#/components/schemas/Gateway-Error-Response'
- $ref: '#/components/schemas/Service-Error-Response'
examples:
Internal-Server-Service-Error-Example:
$ref: '#/components/examples/Internal-Server-Service-Error-Example'
Internal-Server-Gateway-Error-Example:
$ref: '#/components/examples/Internal-Server-Gateway-Error-Example'
Not-Found:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway-Error-Response'
examples:
Not-Found-Gateway-Error-Example:
$ref: '#/components/examples/Not-Found-Gateway-Error-Example'
Method-Not-Allowed:
description: Method Not Allowed
content:
application/json:
schema:
title: Method-Not-Allowed-Response
oneOf:
- $ref: '#/components/schemas/Gateway-Error-Response'
- $ref: '#/components/schemas/Service-Error-Response'
examples:
Method-Not-Allowed-Gateway-Error-Example:
$ref: '#/components/examples/Method-Not-Allowed-Gateway-Error-Example'
Method-Not-Allowed-Service-Error-Example:
$ref: '#/components/examples/Method-Not-Allowed-Service-Error-Example'
Unsupported-Media-Type:
description: Unsupported Media Type
content:
application/json:
schema:
title: Unsupported-Media-Type-Response
oneOf:
- $ref: '#/components/schemas/Gateway-Error-Response'
- $ref: '#/components/schemas/Service-Error-Response'
examples:
Un-Supported-Media-Type-Gateway-Error-Example:
$ref: >-
#/components/examples/Un-Supported-Media-Type-Gateway-Error-Example
Un-Supported-Media-Type-Service-Error-Example:
$ref: >-
#/components/examples/Un-Supported-Media-Type-Service-Error-Example
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Service-Error-Response'
examples:
Forbidden-Service-Example:
$ref: '#/components/examples/Forbidden-Service-Example'
Conflict:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Service-Error-Response'
Too-Many-Requests:
description: Too Many Requests - Rate limit exceeded. Retry after the specified time.
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway-Error-Response'
examples:
Too-Many-Requests-Gateway-Example:
$ref: '#/components/examples/Too-Many-Requests-Gateway-Example'
Service-Unavailable:
description: >-
Service Unavailable - The server is temporarily unable to handle the
request.
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway-Error-Response'
examples:
Service-Unavailable-Gateway-Example:
$ref: '#/components/examples/Service-Unavailable-Gateway-Example'
Gateway-Timeout:
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway-Error-Response'
examples:
Merchant-Creation-For-Enterprise-Request-Example:
value:
partner_user_id: '24564524'
contact_number: '9234567890'
contact_prefix: '91'
email: abc@test.com
Merchant-Creation-Success-Response-Example:
value:
merchant_id: ec689822-9864-4c4d-9d68-222467627901
status_details:
status: SUCCESS
message: Merchant creation is success
File-Upload-Positive-Response-Example:
value:
file_id: '112213'
created_time: '2026-01-06T10:56:25Z'
status_details:
status: SUCCESS
message: File upload is success
File-Download-Response-Example:
value:
- file_id: '112213'
file_download_link: https://pingpongx.com/
Certification-Request:
value:
country_code: CN
merchant_ack: 'YES'
business:
name: payment service provider
name_in_local_language: payment service provider
establishment_date: '1975-03-07'
license_expiry_date: '1975-03-07'
address:
street_name: Schillerstrasse 23
postal_code: '999077'
city: Ras Al Khaimah
district: district1111
state: Ras al Khaymah
products_and_services_category: KC02001008
tax_id_type: VAT
tax_id_number: tax_id_number1111
account_usage:
- ONLINE_MARKETPLACE_TRADING
description: Selling products or purchasing raw materials on online platforms
website: http://www.company.cn
business_proof_file_id: N1234567891011121314151622
documents:
- type: CERTIFICATE_OF_REGISTRATION
sub_type: ACRA
number: DE123456789
file_id: N1234567891011121314151617
business_persons:
- role: AGENT_OR_AUTHORISED_PERSON
first_name: Hongbo
first_name_in_local_language: first name
middle_name: s
middle_name_in_local_language: middle name
last_name: Lin
last_name_in_local_language: last name
alias: Hongbo
nationality: CN
gender: MALE
birth_details:
date: '1975-03-07'
country_code: CN
state: beijing
address:
street_name: Schillerstrasse 23
postal_code: '999077'
city: Ras Al Khaimah
district: district1111
state: Ras al Khaymah
country_code: CN
tax_id_number: tax123456
business_title: Director
documents:
- type: NATIONAL_OR_STATE_ID
sub_type: FRONT
number: ID123456789
expiry_date: '1975-03-07'
issue_date: '1975-03-07'
issuing_authority: Government of China
file_id: N1234567891011121314151617
Certification-Request-Cn:
value:
country_code: CN
merchant_ack: 'YES'
business:
name: payment service provider
name_in_local_language: payment service provider
establishment_date: '1975-03-07'
license_expiry_date: '1975-03-07'
address:
street_name: Schillerstrasse 23
postal_code: '999077'
city: Ras Al Khaimah
district: district1111
state: Ras al Khaymah
products_and_services_category: KC02001008
account_usage:
- ONLINE_MARKETPLACE_TRADING
documents:
- type: CERTIFICATE_OF_REGISTRATION
sub_type: CERTIFICATE_OF_REGISTRATION
number: DE123456789
file_id: N1234567891011121314151617
business_persons:
- role: AGENT_OR_AUTHORISED_PERSON
first_name: Hongbo
first_name_in_local_language: first name
last_name: Lin
last_name_in_local_language: last name
nationality: CN
birth_details:
date: '1975-03-07'
address:
street_name: Schillerstrasse 23
postal_code: '999077'
city: Ras Al Khaimah
district: district1111
state: Ras al Khaymah
country_code: CN
documents:
- type: NATIONAL_OR_STATE_ID
sub_type: FRONT
number: ID123456789
expiry_date: '1975-03-07'
issue_date: '1975-03-07'
issuing_authority: Government of China
file_id: N1234567891011121314151617
- type: NATIONAL_OR_STATE_ID
sub_type: BACK
file_id: N1234567891011121314151617
Certification-Request-Hk:
value:
country_code: CN
merchant_ack: 'YES'
business:
name: payment service provider
name_in_local_language: payment service provider
establishment_date: '1975-03-07'
license_expiry_date: '1975-03-07'
address:
street_name: Schillerstrasse 23
postal_code: '999077'
city: Ras Al Khaimah
district: district1111
state: Ras al Khaymah
products_and_services_category: KC02001008
tax_id_type: VAT
tax_id_number: tax_id_number1111
account_usage:
- ONLINE_MARKETPLACE_TRADING
description: Selling products or purchasing raw materials on online platforms
website: http://www.company.cn
business_proof_file_id: N1234567891011121314151622
documents:
- type: CERTIFICATE_OF_REGISTRATION
sub_type: ACRA
number: DE123456789
file_id: N1234567891011121314151617
business_persons:
- role: AGENT_OR_AUTHORISED_PERSON
first_name: Hongbo
first_name_in_local_language: first name
middle_name: s
middle_name_in_local_language: middle name
last_name: Lin
last_name_in_local_language: last name
alias: Hongbo
nationality: CN
gender: MALE
birth_details:
date: '1975-03-07'
country_code: CN
state: beijing
address:
street_name: Schillerstrasse 23
postal_code: '999077'
city: Ras Al Khaimah
district: district1111
state: Ras al Khaymah
country_code: CN
tax_id_number: tax123456
business_title: Director
documents:
- type: NATIONAL_OR_STATE_ID
sub_type: FRONT
number: ID123456789
expiry_date: '1975-03-07'
issue_date: '1975-03-07'
issuing_authority: Government of China
file_id: N1234567891011121314151617
Certification-Save-Acknowledgement:
value:
status_details:
status: PENDING_SAVED
message: Request is accepted and the further processing is in-progress
Certification-Submit-Acknowledgement:
value:
status_details:
status: PENDING_SUBMITTED
message: Request is accepted and the further processing is in-progress
Certification-Approved-Webhook-Example:
value:
merchant_id: ec689822-9864-4c4d-9d68-222467627901
status: APPROVED
message: KYC request is approved
business_name: business name
business_name_in_local_language: business name in local
Certification-Declined-Webhook-Example:
value:
merchant_id: 99f7f4b6-490c-468b-bd1b-f29310f9ebdd
status: DECLINED
business_name: company.enterprise.name
business_name_in_local_language: 北京科技有限责任公司
message: reject_all
Certification-Rfi-Pending-Webhook-Example:
value:
merchant_id: 27162edf-9429-453e-8289-ddbba0627327
status: RFI_PENDING
business_name: company.enterprise.name
business_name_in_local_language: 北京科技有限责任公司
message: >-
Englishname is not
standard-英文名不规范,fm_return_company_certificates_expiration-补充材料_证照过期_企业
Get-Certification:
value:
country_code: CN
merchant_ack: 'YES'
business:
name: payment service provider
name_in_local_language: payment service provider
establishment_date: '1975-03-07'
license_expiry_date: '1975-03-07'
address:
street_name: Schillerstrasse 23
postal_code: '999077'
city: Ras Al Khaimah
district: district1111
state: Ras al Khaymah
products_and_services_category: KC02001008
tax_id_type: VAT
tax_id_number: tax_id_number1111
account_usage:
- ONLINE_MARKETPLACE_TRADING
description: Selling products or purchasing raw materials on online platforms
website: http://www.company.cn
business_proof_file_id: N1234567891011121314151622
documents:
- type: CERTIFICATE_OF_REGISTRATION
sub_type: ACRA
number: DE123456789
file_id: N1234567891011121314151617
business_persons:
- role: AGENT_OR_AUTHORISED_PERSON
first_name: Hongbo
first_name_in_local_language: first name
middle_name: s
middle_name_in_local_language: middle name
last_name: Lin
last_name_in_local_language: last name
alias: Hongbo
nationality: CN
gender: MALE
birth_details:
date: '1975-03-07'
country_code: CN
state: beijing
address:
street_name: Schillerstrasse 23
postal_code: '999077'
city: Ras Al Khaimah
district: district1111
state: Ras al Khaymah
country_code: CN
tax_id_number: tax123456
business_title: Director
documents:
- type: NATIONAL_OR_STATE_ID
sub_type: FRONT
number: ID123456789
expiry_date: '1975-03-07'
issue_date: '1975-03-07'
issuing_authority: Government of China
file_id: N1234567891011121314151617
certification_status: APPROVED
message: KYC approved
merchant_type: ENTERPRISE
product_code: PAYMENT_CORE
Wallet-Activation-Request-Example:
value:
currency_code: USD
bank_country_code: US
Wallet-Activation-Response-Example:
value:
status_details:
status: PENDING
message: >-
Request is accepted successfully and wallet activation is in
progress
Wallet-Activation-Available-Webhook-Example:
value:
virtual_account_id: 59b746f1-8fcc-4801-8b90-b0204140a462
virtual_account_number: '73380000000304551'
account:
type: CHECKING
holder_name: 北京创新科技有限公司
currency_code: USD
bank:
name: Citibank
code: '006'
branch_number: '01'
city: New York
address_line: 111 Wall Street, New York, New York 10043, United States
postal_code: '10043'
country_code: US
routing_number: '031100209'
swift_code: GEOORUMMXXX
status: AVAILABLE
merchant_id: 205dff66-ff47-4d72-82ac-865dbe909040
Wallet-Activation-Closed-Webhook-Example:
value:
virtual_account_id: 3e5061de-f232-49f5-bef6-71bcaf6431fb
virtual_account_number: '73380000000304607'
account:
currency_code: USD
status: CLOSED
message: as CITI requested
merchant_id: 91eb2008-bee1-4bb9-84ea-e9f372a76e95
Wallet-Activation-Declined-Webhook-Example:
value:
virtual_account_id: 3e5061de-f232-49f5-bef6-71bcaf6431fb
virtual_account_number: '73380000000304607'
account:
currency_code: USD
status: DECLINED
message: as CITI requested
merchant_id: 91eb2008-bee1-4bb9-84ea-e9f372a76e95
Get-Wallet-Response-Example:
value:
- virtual_account_id: R200801012359590001
virtual_account_number: '38879371'
virtual_account_status: AVAILABLE
message: Virtual account status is available
account:
type: CHECKING
iban: SE1498203030437006071356
holder_name: Carol Parisian
currency_code: HNL
bank:
name: CITI Bank HongKong Branch
code: '37'
branch_number: '690'
city: South Devyn
address_line: Apt. 883
postal_code: '605826'
country_code: SO
routing_number: '687869237'
swift_code: BETFSJGNJ8F
sort_code: '430391'
Get-Wallet-Balances-Response-Example:
value:
- virtual_account_id: ec689822-9864-4c4d-9d68-222467627901
account_type: BALANCE_ACCOUNT
currency_code: USD
available_amount: 399.35
Account-Linkage-Request-Example:
value:
creditor_account:
holder_type: PERSONAL
holder_contact_number: 007 3700 7457
number: '703912345678'
name: SHASHANK VIJAYSHANKAR TIWARI
currency_code: INR
iban: HU58711204120061837086422231
document_type: CHINESE_RESIDENCE_PERMIT
document_number: CS8899966
creditor:
type: '00'
name: SHASHANK VIJAYSHANKAR TIWARI
contact_number: '9876543210'
contact_prefix: '91'
email: abc@pp.com
partner_user_id: P298UI839KADY381
address:
city: THANE
state: MAHARASHTRA
country_code: IN
address_line: SUMAN HEIGHTS LODHA HERITAGR NAVNEET NAGAR MAHARASHTRA THANE INDIA
street_name: ROYAL STREET
postal_code: '5110'
creditor_bank:
name: BANK OF BARODA
code: '6'
branch_name: THANE BRANCH
branch_number: '391'
swift_code: CITIINHFXXX
routing_number: '6391'
ifsc_code: HDFC0000001
sort_code: '87'
address:
city: THANE
state: MAHARASHTRA
country_code: IN
address_line: SUMAN HEIGHTS LODHA HERITAGR NAVNEET NAGAR MAHARASHTRA THANE INDIA
file_id: 8f7d6e5c-4b3a-2f1d-9e8c-7b6a5d4c3f2e
Account-Linkage-Request-Example-HK:
value:
creditor_account:
holder_type: PERSONAL
holder_contact_number: 007 3700 7457
number: '4569897132589457'
name: 北京科技有限责任公司
currency_code: HKD
iban: HU58711204120061837086422231
document_type: CHINESE_NATIONAL_ID_CARD
document_number: CS8899966
creditor:
type: '00'
name: 北京科技有限责任公司
contact_number: '9876542154723210'
contact_prefix: '91'
email: pingpong@pp.com
partner_user_id: ece724af-99de-47a5-867c-c707402ac67e
address:
city: Wan Chai
state: Wan Chai District
country_code: HK
address_line: 150 Kennedy Road, Wan Chai, Wan Chai District, Hong Kong (HKG).
street_name: 150 Kennedy Road
postal_code: HKG
creditor_bank:
name: 北京科技有限责任公司
code: HSBCHKHH
branch_name: The Hongkong and Shanghai Banking Corporation Limited
branch_number: '053'
swift_code: HSBCHKHH053
address:
city: Central
state: Hong Kong
country_code: HK
address_line: Central, Hong Kong, HK.
file_id: NjSvXYrw3OAyMDI2MDIxMjE1MzExMTkwMjgucG5n.png
Account-Linkage-Request-Example-CN:
value:
creditor_account:
holder_type: COMPANY
holder_contact_number: 007 3700 7457
number: '7894561523255'
name: 北京创新科技有限公司
currency_code: CNY
iban: HU58711204120061837086422231
document_type: CHINESE_RESIDENCE_PERMIT
document_number: CS8899966
creditor:
type: '00'
name: SHASHANK VIJAYSHANKAR TIWARI
contact_number: '101457856'
contact_prefix: '86'
email: pingpong@pp.com
creditor_partner_user_id: ece724af-99de-47a5-867c-c707402ac67e
address:
city: Changpingqu Beijing
state: Beijing
country_code: CN
address_line: >-
10 West, Shahedonmendajie, Changpingqu Beijing, 102206 Beijing,
CHN.
street_name: 10 West, Shahedonmendajie
postal_code: '102206'
creditor_bank:
name: BNP PARIBAS (CHINA) LTD
code: BNPACNBJ
branch_name: BEIJING BRANCH
branch_number: XXX
swift_code: BNPACNBJXXX
address:
city: CHAOYANG DISTRICT, BEIJING
state: CHAOYANG DISTRICT, BEIJING
country_code: CN
address_line: >-
BNP PARIBAS (CHINA) LTD (BEIJING BRANCH), UNIT 01-04, 22-26, FLOOR
16, BUILDING 1 JIANGUOMENWAI AVENUE, CHAOYANG DISTRICT, BEIJING,
China
file_id: NjSvXYrw3OAyMDI2MDIxMjE1MzExMTkwMjgucG5n.png
Account-Linkage-Response-Example:
value:
status_details:
status: PENDING
message: >-
Request received successfully and the further processing is
in-progress
Account-Linkage-Available-Webhook-Example:
value:
merchant_id: ClientCustomerID1234
creditor_id: R202501080950209789
status: AVAILABLE
message: Creditor is successfully created
Account-Linkage-Declined-Webhook-Example:
value:
merchant_id: 91eb2008-bee1-4bb9-84ea-e9f372a76e95
status: DECLINED
creditor_id: ca83c6b2-d357-4dc1-805a-0050e4e10e68
message: 客户要求拒绝
Get-Account-Linkage-Response-Example:
value:
- creditor_id: R202501080950209789
creditor_status: AVAILABLE
message: Request is in-progress
created_time: '2026-01-06T10:56:25Z'
creditor_account:
holder_type: PERSONAL
holder_contact_number: 007 3700 7457
number: '703912345678'
name: SHASHANK VIJAYSHANKAR TIWARI
currency_code: INR
iban: HU58711204120061837086422231
document_type: CHINESE_RESIDENCE_PERMIT
document_number: CS8899966
type: CHECKING
creditor_bank:
name: BANK OF BARODA
code: '6'
branch_name: THANE BRANCH
branch_number: '391'
swift_code: CITIINHFXXX
routing_number: '6391'
ifsc_code: HDFC0000001
sort_code: '87'
type: RECIPIENT BANK
address:
city: THANE
state: MAHARASHTRA
country_code: IN
address_line: >-
SUMAN HEIGHTS LODHA HERITAGR NAVNEET NAGAR MAHARASHTRA THANE
INDIA
creditor:
type: '00'
name: SHASHANK VIJAYSHANKAR TIWARI
contact_number: '9876543210'
contact_prefix: '91'
email: abc@pp.com
address:
city: THANE
state: MAHARASHTRA
country_code: IN
address_line: >-
SUMAN HEIGHTS LODHA HERITAGR NAVNEET NAGAR MAHARASHTRA THANE
INDIA
street_name: ROYAL STREET
postal_code: '5110'
file_id: 8f7d6e5c-4b3a-2f1d-9e8c-7b6a5d4c3f2e
Fx-Query-Request-Example:
summary: Sample FX Query request
value:
buy_currency_code: CNH
buy_amount: 100.11
sell_currency_code: USD
sell_amount: 80.1
reference_id: '12456'
seller_markup: CN-150
Fx-Query-Success-Example:
summary: Sample 200 response
value:
buy_currency_code: CNH
buy_amount: 100.11
sell_currency_code: USD
sell_amount: 80.1
value_date: '2025-12-15'
fx_rate_id: '16098876465273400000'
fx_rate: 7.13909
expiry_time: '2025-08-22T12:00:00Z'
reference_id: '12456'
Payment-To-Wallet-Request:
value:
message_id: bulk123
payments:
- payment_info:
- transaction:
partner_user_reference: PUR1234556567wegry
end_to_end_id: SM37864746
currency_code: USD
amount: 1000
payment_details: INV123
method:
type: LOCAL
method: BKT
creditor:
account:
virtual_account_id: VA202501080950209789
Payment-To-External-Request:
value:
payments:
- debtor:
account:
virtual_account_id: VA202501080950209789
payment_info:
- transaction:
partner_user_reference: PUR1234556567wegry
end_to_end_id: SM37864746
equivalent_currency_code: USD
currency_code: USD
amount: 1000
payment_details: INV123
fx_rate_id: '3885000000000000000'
purpose_code: '1001'
payment_type: PAYOUT
file_id: '112213'
method:
type: CROSS_BORDER
method: CBFT
creditor:
id: R202501080950209789
Payment-Validation-Success-Example:
value:
status: PENDING
message: Request is in-progress
message_id: bulk123
Payment-Validation-Full-Rejection-Example:
value:
ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
status: REJECTED
message: Request is rejected
message_id: bulk123
transaction:
- end_to_end_id: SM37864746
error_details:
- issue: property emailAddress is mandatory and it cannot be empty
action: please provide valid value for property emailAddress
code: VC00010
Payment-Validation-Partial-Rejection-Example:
value:
ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
status: PARTIALLY_REJECTED
message: Request is partially rejected
message_id: bulk123
transaction:
- end_to_end_id: SM37864746
error_details:
- issue: property emailAddress is mandatory and it cannot be empty
action: please provide valid value for property emailAddress
code: VC00010
Payment-To-Wallet-Rejected-Webhook:
value:
message_id: bulk123
debtor:
account:
number: R202501080950209789
creditor:
account:
virtual_account_id: VA202501080950209789
transaction:
partner_user_reference: PUR1234556567wegry
end_to_end_id: SM37864746
currency_code: USD
amount: 1000
payment_details: INV123
uetr: '202501092053115499258'
created_time: '2026-01-06T10:56:25Z'
status: REJECTED
message: Payment is rejected
error_details:
- issue: property end_to_end_id is mandatory and it cannot be empty
action: please provide valid value for property end_to_end_id
code: VC00010
Payment-To-External-Rejected-Webhook:
value:
merchant_id: ec689822-9864-4c4d-9d68-222467627901
debtor:
account:
virtual_account_id: VA202501080950209789
creditor:
id: R202501080950209789
transaction:
partner_user_reference: PUR1234556567wegry
end_to_end_id: SM37864746
currency_code: USD
amount: 1000
payment_details: INV123
uetr: '202501092053115499258'
created_time: '2026-01-06T10:56:25Z'
completed_time: '2026-01-06T11:00:25Z'
status: REJECTED
message: Payment is rejected
error_details:
- issue: property end_to_end_id is mandatory and it cannot be empty
action: please provide valid value for property end_to_end_id
code: VC00010
Payment-To-Wallet-Success-Webhook:
value:
message_id: bulk123
debtor:
account:
number: R202501080950209789
creditor:
account:
virtual_account_id: VA202501080950209789
transaction:
partner_user_reference: PUR1234556567wegry
end_to_end_id: SM37864746
currency_code: USD
amount: 1000
payment_details: INV123
uetr: '202501092053115499258'
created_time: '2026-01-06T10:56:25Z'
status: SUCCESS
Payment-To-External-Success-Webhook:
value:
merchant_id: ec689822-9864-4c4d-9d68-222467627901
debtor:
account:
virtual_account_id: VA202501080950209789
creditor:
id: R202501080950209789
transaction:
partner_user_reference: PUR1234556567wegry
end_to_end_id: SM37864746
equivalent_currency_code: USD
currency_code: USD
amount: 1000
payment_details: INV123
uetr: '202501092053115499258'
charges_currency: CNH
charges_amount: 100.11
fx_rate_id: '3885000000000000000'
fx_rate: 0
created_time: '2026-01-06T10:56:25Z'
completed_time: '2026-01-06T11:00:25Z'
status: SUCCESS
Get-Payment-To-Wallet:
value:
message_id: bulk123
payments:
- debtor:
account:
number: R202501080950209789
creditor:
account:
virtual_account_id: VA202501080950209789
transaction:
partner_user_reference: PUR1234556567wegry
end_to_end_id: SM37864746
currency_code: USD
amount: 1000
payment_details: INV123
uetr: '202501092053115499258'
created_time: '2026-01-06T10:56:25Z'
completed_time: '2026-01-06T11:00:25Z'
status: SUCCESS
Get-Payment-To-External:
value:
merchant_id: ec689822-9864-4c4d-9d68-222467627901
payments:
- debtor:
account:
virtual_account_id: VA202501080950209789
creditor:
id: R202501080950209780
transaction:
partner_user_reference: PUR1234556567wegry
end_to_end_id: SM37864746
equivalent_currency_code: USD
currency_code: USD
amount: 1000
payment_details: INV123
uetr: '202501092053115499258'
charges_currency_code: CNH
charges_amount: 100.11
fx_rate: 0
created_time: '2026-01-06T10:56:25Z'
completed_time: '2026-01-06T11:00:25Z'
status: SUCCESS
Rfi-Response:
value:
rfi_id: RFI1234
questions:
- question_id: Q123456789
information_request:
- information_name: id_doc_front
answer: string
Rfi-Response-Acknowledgement:
value:
rfi_id: RFI1234
rfi_status: OPEN
questions:
- question_id: Q123456789
information_request:
- information_name: id_doc_front
answer: string
Rfi-Submit:
value:
rfi_id: RFI1234
Rfi-Submit-Acknowledgement:
value:
status: CLOSED
Get-Rfi:
value:
- rfi_id: string
type: string
status: string
created_time: '2026-03-02T17:46:10.833Z'
expiry_time: '2026-03-02T17:46:10.833Z'
creditor_id: string
questions:
- question_id: Q123456789
description_code: string
description_english: string
description_chinese: string
information_request:
- information_name: id_doc_front
information_type: text
answer: string
certification_source:
merchant_type: ENTERPRISE
role: UBO
first_name: string
middle_name: string
last_name: string
first_name_in_local_language: string
middle_name_in_local_language: string
last_name_in_local_language: string
Transaction-Report:
value:
- debtor:
account:
number: '456456547'
branch_code: VA202501080950209789
virtual_account_id: VA202501080950209789
creditor:
id: R202501080950209789
account:
number: '456456547'
branch_code: VA202501080950209789
virtual_account_id: VA202501080950209789
transaction:
end_to_end_id: SM37864746
currency_code: CNY
amount: 10000
buy_currency_code: CNY
buy_amount: 10000
sell_currency_code: USD
sell_amount: 1000
payment_details: INV123
uetr: '202501092053115499258'
fx_rate: 0
payment_type: PAYOUT
created_time: '2026-01-06T10:56:25Z'
completed_time: '2026-01-06T11:00:25Z'
status: SUCCESS
Transaction-Report-For-WITHDRAW-INBOUND:
value:
- status: SUCCESS
creditor:
account:
number: '6258591914237939405'
transaction:
end_to_end_id: A1781686585
currency_code: USD
amount: 21.71
buy_currency_code: CNY
buy_amount: 154
uetr: WC0926061716563217599935
fx_rate: 7.0945
payment_type: WITHDRAW
created_time: '2026-06-17T08:56:32Z'
completed_time: '2026-06-17T11:42:26Z'
- status: SUCCESS
debtor:
account:
number: newAccountNo
transaction:
currency_code: USD
amount: 8000001
sell_currency_code: USD
sell_amount: 8000001
uetr: '202606162012563459642'
fx_rate: 1
payment_type: INBOUND
created_time: '2026-06-16T12:12:56Z'
completed_time: '2026-06-16T12:21:00Z'
Transaction-Report-For-PAYOUT:
value:
- status: SUCCESS
creditor:
account:
number: '1781610740'
transaction:
end_to_end_id: A1781689100
currency_code: USD
amount: 257
buy_currency_code: USD
buy_amount: 257
uetr: SP0926061717382948219612
fx_rate: 1
payment_type: PAYOUT
created_time: '2026-06-17T09:38:29Z'
completed_time: '2026-06-17T11:39:04Z'
Balance-Report:
value:
- virtual_account_id: ec689822-9864-4c4d-9d68-222467627901
uetr: '202501092053115499258'
opening_balance: 5000
closing_balance: 4000
created_time: '2026-01-06T10:56:25Z'
amount: 1000
currency_code: USD
direction: debit
Inbound-Payment-Notification-Example:
summary: Example inbound payment notification payload
value:
merchant_id: ClientCustomerID1234
debtor:
name: Hongbo
account_number: '1234567'
country_code: CN
address: Ras Al Khaimah
debtor_bank:
name: Citi Bank US
creditor:
name: Su Lin
account_number: '78945615'
address: Schillerstrasse 23
transaction:
uetr: de2da6c9-18be-48d4-8053-867ed90a316a
end_to_end_id: E202501080950209789
amount: 1000
currency_code: USD
payment_details: Goods sold
status: SUCCESS
inbound_type: INBOUND
RFI-Notification-Example:
summary: Example RFI notification payload
value:
merchant_id: ClientCustomerID1234
rfi_id: RFI123
type: KYC
status: OPEN
created_time: '2025-01-08T09:50:20Z'
expiry_time: '2025-02-08T09:50:20Z'
creditor_id: CR21245734
questions:
- question_id: Q123654
description_code: KYCDR02001
description_english: >-
[Business person name] - Please upload a photo of an original ID.
(not a copy or screenshot)
description_chinese: '[姓名] - 提供的证件照片非证件原件照片，请提供证件原件照片。'
information_request:
- information_name: ID Photo
information_type: TEXT
certification_source:
merchant_type: ENTERPRISE
role: UBO
first_name: Hongbo
middle_name: Su
last_name: Lin
first_name_in_local_language: first name
middle_name_in_local_language: middle name
last_name_in_local_language: last name
Bad-Request-Gateway-Error-Example:
value:
httpCode: '400'
httpMessage: Bad Request
moreInformation: please provide valid value for request
Bad-Request-Service-Error-Example:
value:
ref_id: ec689822-9864-4c4d-9d68-222467627901
error_details:
- issue: record that you are searching is not found
action: resend the request with valid values
code: VC00003
Unauthorized-Gateway-Error-Example:
value:
httpCode: '401'
httpMessage: Unauthorized
moreInformation: The server could not verify that you are authorized to access the URL
Unauthorized-Service-Error-Example:
value:
ref_id: ec689822-9864-4c4d-9d68-222467627902
error_details:
- issue: User not authorized for this functionality
action: please use valid credentials to access this functionality
code: CC00007
Internal-Server-Service-Error-Example:
value:
ref_id: ec689822-9864-4c4d-9d68-222467627902
error_details:
- issue: unable to serve your request at this moment
action: Please refer to documentation provided or contact support team
code: CC00004
Internal-Server-Gateway-Error-Example:
value:
httpCode: '500'
httpMessage: Internal Server Error
moreInformation: Internal Server Error
Not-Found-Gateway-Error-Example:
value:
httpCode: '404'
httpMessage: Not Found
moreInformation: No resources match requested URI
Method-Not-Allowed-Gateway-Error-Example:
value:
httpCode: '405'
httpMessage: Method Not Allowed
moreInformation: The method is not allowed for the requested URL
Method-Not-Allowed-Service-Error-Example:
value:
ref_id: ec689822-9864-4c4d-9d68-222467627901
error_details:
- issue: Method not supported
action: Method not supported for this endpoint, please use valid http verb
code: CC00001
Un-Supported-Media-Type-Gateway-Error-Example:
value:
httpCode: '415'
httpMessage: Unsupported Media Type
moreInformation: Unsupported Content-Type application/octet-stream
Un-Supported-Media-Type-Service-Error-Example:
value:
ref_id: ec689822-9864-4c4d-9d68-222467627902
error_details:
- issue: Media type not supported
action: please use valid content-type in header
code: CC00002
Forbidden-Service-Example:
value:
ref_id: ec689822-9864-4c4d-9d68-222467627902
error_details:
- code: CC00008
issue: User does not have privilege to access this functionality.
action: Please reach out to support team to enable this feature.
Idempotency-Id-Conflict-Example:
value:
ref_id: ec689822-9864-4c4d-9d68-222467627902
error_details:
- issue: Idempotency-Id provided is currently being used in another request
action: please do not repeat the same request again
Too-Many-Requests-Gateway-Example:
value:
httpCode: '429'
httpMessage: Too Many Requests
moreInformation: Rate Limit exceeded
Service-Unavailable-Gateway-Example:
value:
httpCode: '503'
httpMessage: Service is temporarily unavailable
moreInformation: Retry the request after some time
Gateway-Timeout-Example:
value:
httpCode: '504'
httpMessage: Gateway Timeout
moreInformation: 'Response took longer than timeout: PTxxS'