Search Overlay

Getting Started

Change Log

Version Date Details
V1 25 Nov 2022 - Add additional bank name for Wallet Payment Instruments
V1 18 Oct 2022 - Add additional statusReason codes for FAILED wallet transactions
V1 04 Oct 2022 - Fix refund examples url
V1 13 Sept 2022 - Add expected transaction volume for legal entities
V1 12 Aug 2022 - Update API documentation for onboarding legal customers
V1 12 Jul 2022 - Major API Restructuring and clarifications to Overview, Getting Started and Wallet operations sections
V1 12 Jul 2022 - Adding Change customer country functionality in the Wallet Operations documentation
V1 27 Jun 2022 - Update Screening API
V1 3 Jun 2022 - Clarifications on updating customer's country of registration
V1 7 Jun 2022 - Error messages added
V1 2 Jun 2022 - Added new KYC document types for legal entity customers
V1 1 Jun 2022 - Added new error code for conflict during onboarding
V1 1 Jun 2022 - Clarifications on the ownershipPercentage property. Fixed bug in documentation.
V1 26 May 2020 - Update Transaction screening endpoint
V1 17 May 2022 - Clarifications on the 'Get customer - Generic' endpoint
V1 14 Apr 2022 - Add screeningId to Transfers
V1 12 Apr 2022 - Add customerIds (array), accountIds(array) and merchantRefNums(array) to NotificationResendTask
V1 07 Apr 2022 - Updates on the transaction screening API
V1 01 Apr 2022 - Add example request and response for create customer wallet for a legal entity
V1 01 Apr 2022 - added endpoint for tranasaction screening
V1 28 Mar 2022 - added notifications API specific error codes.
V1 10 Mar 2022 - ownershipPercentage set to optional. Add representatives array to legal entity customer.
V1 28 Feb 2022 - Added transfer reason
V1 23 Feb 2022 - Remove LegalEntityOwner
V1 23 Feb 2022 - Add model KybDocument. Add kybDocuments to CustomerLegalEntity,kybDocuments and kyc to LegalEntityPerson.
V1 18 Feb 2022 - Add NotificationResendTask API to request resend of webhooks
V1 15 Feb 2022 - Fixed requiredActions for restrictions
V1 9 Feb 2022 - Added fields in KYC section for specifying the verifications vendor
V1 9 Feb 2022 - Update on corporate customer address fields
V1 25 Jan 2022 - Updates to corportate customers API
V1 20 Jan 2022 - Updated documentation for account assigned webhook format
V1 18 Jan 2022 - Updated RT examples for currency GBP
V1 17 Jan 2022 - Updated Card & RT flows
    - Added Payment Handle webhooks
V1 12 Jan 2022 - Added support for corporate customers
V1 27 Dec 2021 - Added new restrictions synchronization APIs
V1 21 Dec 2021 - Updated error documentation
V1 2 Dec 2021 - Added customer's externalId to the response of the Get accounts endpoints
V1 1 Dec 2021 - Marking required and optional fields; fixed error response format; documentation added
V1 25 Nov 2021 - Added risk fields for wallet creation and transaction
V1 25 Nov 2021 - Examples & documentation updated; added appType in deviceInfo
    - Updated Payment Handle samples with deviceInfo
V1 22 Nov 2021 - Added bank account detail - BIC
    - Updated examples
    - Removed initial balance when creating a wallet - a separate transfer transaction must be used
V1 17 Nov 2021 - Removed pagination from get customer accounts; the API returns a list of accounts
    - URL for GET instruments changed; customerId converted to required query parameter
    - Added wallet transaction statusReason
V1 17 Nov 2021 - Added get customer's payment instruments endpoint
    - Added KYC parameters, following Risk & Compliance workshops
    - Added clarifications on virtual IBAN assignment; webhook for virtual IBAN assigned
    - Added deviceInfo; customerIp updated to mandatory for all payment APIs
    - Added information about onboarding idempotency; removed "phone" field; one of email or mobile is required
V1 10 Nov 2021 - Added the parameter verifiedInstrument to Payment handle
V1 08 Nov 2021 - Added Payment Workflows
    - Labeled Mandatory Fields as required
V1 10 Aug 2020 - Document Release

API Basics

The API is constructed around REST and has the following features:

  • Definite resource-oriented URLs

  • Receives JSON-encoded request bodies

  • Returns JSON-encoded responses

  • Communicates using standard HTTP response codes, authentication, and verbs.

  • Message body: This must contain valid Paysafe JSON objects as required for the type of request. Not all API calls require a message-body; for example, GET requests do not require a body.

  • Resource ID: Identifies the unique ID of a resource.


Paysafe's REST API uses API keys to authenticate your request in the following format:

  • Key Username – MerchantXYZ

  • Key Password – 20881dff9bb4020a89e8ac44

The case-sensitive API key is sent using HTTP Basic Authentication. To use HTTP Basic Authentication, you must send the API key credentials using the Authorization header with every request.

The Authorization header is constructed as follows:

  1. The Key Username and Key Password are combined into a string separated by a colon, e.g.,“Key Username:Key Password”.

  2. The resulting string literal is then encoded using Base64 (to allow sending of special characters).

  3. The authorization method and а space (i.e., “Basic”) are then put before the encoded string.

For example, using the Key Username and Password examples above, the header is formed as follows:

Authorization: Basic TWVyY2hhbnRYWVo6MjA4ODFkZmY5YmI0MDIwYTg5ZThhYzQ0

For additional details, please refer to

Your Production API key will be different from your Test API key. Contact your account manager for details. You must keep your API keys safe and ensure that it is used appropriately for your needs.

Get your secret API key

Please contact your business relationship manager or reach out to for API keys and Test/Production accounts.

All your APIs will use the same API key.


Test accounts enable you to process API transactions that mirror the functionality of the Production environment.

Transactions processed in the Test environment are executed on a simulator. Depending on the information provided with the transaction request, the simulator returns either a successful (approved) or failed (declined) response.

With the API, you can:

  • Verify support for all the operation types that you require.

  • Review all common errors as well as unique errors that may occur for each operation.

  • Verify the length and format for all attributes you send.

For access to Test accounts and credentials, contact your account manager or reach out to Your Test account has access to the Test version of the Paysafe Business Portal, where you can view the status of your Test transactions.

Test URL

To test your integration with Paysafe, use the following Test URLs:

For example:{payment_id}

Going live

Once you are satisfied with your integration to the Test environment, you must repeat the configuration changes made to your Test account on your Production account.

You cannot use your Test credentials to process transaction requests in the Production environment.

Go Live Checklist

  1. You must have a production account and access to Business Portal.

  2. You must have a Secret API Key for the production environment.

  3. You must have Webhooks configured for all the events.

  4. You must use the Production URL for your API calls.

Production URL

To process live requests with Paysafe, use the following Production URL:



For example:




In the case where an API GET request returns multiple results, Paysafe returns the first 10 records by default and uses HATEOAS links to provide page navigation. In addition to the default behavior, it is also possible to control the number of results and starting point by passing in query parameters as described in this section.

Global Invalid Characters

You must not include any of the characters in this table as values in any of your request parameters. Object. If you do, your request will result in an error.

ISO Standards

ISO standards add value by providing the common business process data semantics to be used in the API based exchanges. This section presents you with codes for four areas - Currency, Province, State, and Country.

Please refer Miscellaneous for Global Invalid Characters, ISO Standards, Currency Codes, Province Codes, State Codes, and Country Codes.

Features in development

Documentation for new features and capabilities currently in development is exposed as means of collecting customer feedback. The feedback allows Paysafe to evolve the product and decide on future product direction.

These features:

  • might not get released in general availability for all customers

  • might get changed before being released in general availability

  • might be enabled in a test environment for selected Paysafe customers and partners

  • might require contract amendments to be accessible to your environment

Parts of the API that are part of new unreleased feature would be annotated with In Development comment.

Contact your Paysafe account manager for more details on the product roadmap.

Legal and Community