Payments API Overview

General API Information

The Convera API Suite provides a payment processing platform to accommodate high-volume domestic and FX transactions with API functionality for payment batching, processing, reconciliation, and sanctions visibility. Additionally, the API suite contains tools that help augment your system workflow and developer productivity. The transaction platform API allows Customers to make payments, manage workflow, and reconcile settlement details through API requests or webhooks.

Customers are able to create batches of payments across multiple trade and settlement currency combinations with access to 140+ currencies and 200+ countries.

The Convera API Suite uses a REST-based API with a JSON-structured payload.

API Security

The API Suite offers two methods for authentication: OAuth2.0 and PKCS12 client certificate. To use either method, you will need to contact the Convera onboarding team to provision a sandbox or production account. Once complete, you may proceed with connectivity testing through certificate or API key. Convera does not support self-service Partner sign-up at this time.

OAuth2.0 Authentication

The preferred method of authentication to the API is OAuth2.0. Using this method, the Partner will be assigned credentials that will be used to retrieve an API token. This token will be attached to each API request. A new token will need to be acquired every 30 minutes or the request will be rejected.

OAuth2.0 API URLs

https://oauth.api.convera.com/masspayments
https://oauth.api.convera.com/token
https://masspaysandbox-oauth.api.convera.com/masspayments
https://masspaysandbox-oauth.api.convera.com/token

PKSC12 Client Certificate

The alternate method of authentication is the PKSC12 client certificate. In this method, all API calls should include a valid certificate associated with the Partner ID. Any calls without a client certificate will be rejected.

Before a certificate expiration, a new client certificate will be issued to a Partner for an uninterrupted access.

Certificate API URLs

https://api.convera.com/v1/masspayments
https://masspaysandbox.api.convera.com/masspayments/

Usage Guidelines

In creation of new user-specified resources using PUT methods, a unique external ID must be used. This ID will need to be unique across the entire Partner account and all associated child Customer accounts. Examples include Create new Batch and Add Payment to Batch endpoints.

  • Acceptable external IDs must be alphanumeric strings (hyphens, underscores, [a-zA-Z0-9-_]) up to 38 chars long

In creation of Convera-identified resources or generation of query data, a POST method will be used. Examples include Create Quote for Holding Order and Commit Payment Order endpoints.

  • Any identifiers will be system generated and returned to the caller

Rate Limiting

  • Currently, all Convera Partners are subject to a limit of 500 requests per minute
  • If a request allows the submission for multiple resources, a limit will be imposed for the total count of input resources
  • If a result assumes a collection of resources, a limit will be imposed for the total count of output resources
  • Default timeout for incoming HTTP requests is 100 seconds

Formatting Standards

  • All dates and timestamp types provided by Convera use ISO 8601 and be in UTC unless specifically indicated
    • Example: 2022-01-01 12:15:30Z
  • All currency codes are defined as in ISO 4217
    • Example: USD, EUR, JPY
  • All country codes are defined as in ISO 3166 two-letter code (alpha-2)
    • Example: US, NP, AU
  • All amounts should be defined and submitted as an integer type and assumed to be in cents (minor currency unit) value. The number of cents are defined in ISO 4217
    • Example: 10089 would represent 100.89 USD, or 10089 JPY, or 10.089 KWD as each currency specifies a different minor currency unit (2 for USD, 0 for JPY, and 3 for KWD).
  • The following characters are reserved in JSON and must be properly escaped to be used in strings. Only SWIFT-accepted characters are allowed:
    • Double quote (“) is replaced with \"
    • Backslash () is replaced with a \\
    • Backspace is replaced with \b
    • Form feed is replaced with \f
    • Newline is replaced with \n
    • Carriage return is replaced with \r
    • Tab is replaced with \t

What’s Next

Ready to get started? Check out our Quickstart Guide and start making test payments in minutes!