What are they?
The Client ID and Client Secret are unique credentials that allow us to recognize which test application you are using.
Important! Your Client ID and Client Secret identify you and are essential to protecting yourself and your customers. Keep them in a very safe place.
This is the public identifier of your application. It’s used in every call so we can tell who’s requesting information.
This is the private identifier of your application. It allows us to verify your identity in the authentication step of our APIs.
How do I get them?
You'll first need to register an app in your API Keys workspace.
API Keys Workspace
You can access the workspace through your profile. The workspace is where you can add and manage your apps.
Register a New App
Go to API Keys. Then, select Register a New App. You'll see a series of fields asking you about your app or product.
You’ll need to create a client using the Create a New Client endpoint for your respective market. For more details, look up the documentation for the onboarding/registration PSD2 API in your market. Credentials will be issued based on your eIDAS certificate regardless of your location.
Before you can start testing our APIs, you'll need to authenticate with the Authorize API. There are variations on the type of OAuth that you’ll need to use—two-legged, three-legged and card authorization—which is determined by the kind of information you’re trying to access.
Used when not providing identity information or financial history (e.g., exchanging rewards or submitting product applications).
Pay with Points, Onboarding
How it works
- Make a POST request with your Client ID/Client Secret (base64 encoded) and scopes to Citi servers. This tells Citi who you are, what APIs you're using and what degree of access to your users’ accounts you’d like.
- If the credentials pass, we need a response with an access token, which enables you to make further two-legged API calls.
- When your user takes an action that requires two-legged API calls, include your access token in the request.
Used when sharing sensitive data that requires customer consent (e.g., checking balances, personal identity information).
PSD2 Clients Only
You’ll only be using three-legged authentication, which requires the user to input their personal banking credentials. Before you can start, you'll need to authenticate with the Authorize API.
Accounts, Customers, Money Movement, Cards
How it works
- Create a custom URL that redirects to a Citi log-in endpoint including the following parameters: your client ID, state, country and scope.
- Once you've submitted the parameters, we'll ask your end-user to log in via the Citi portal.
- Once they've successfully logged in, we'll redirect them to your redirect URL.
- Then, we pass the authorization code to you as a variable in the URL.
- You can then exchange the authorization code for an access token via POST command.
Used when enrolling customers in certain services that require accessing sensitive personal data, like Rewards Redemption and Easy Payment Plan in Hong Kong.
How it works
Enroll and Generate Card Access Token
- Make a POST request with countryCode and businessCode to authorize the customer.
- If the user authorization is successful, an access token is generated and a one-time password is sent to their registered mobile number.
- The customer completes their registration by validating the OTP and receives a notification from the successful registration.
Activate Card Access Token
Separate token activation for each credit card held by the customer.
- Make a POST request with countryCode and businessCode to activate the token.
- An access token can be refreshed to generate a fresh access token. If your access token has expired and you still have a valid refresh token, you can exchange it for a new set of valid access and refresh tokens.
- An access token can also be revoked. The revoke call will terminate the access granted by Citi customers to your application.
Now it’s time for the fun part. Choose an API and start testing.
What to do
Our API Documentation will show you how to format your HTTPS request. Include your access token and the information needed for the API. From there, use the response for your application and you’re all set.
Now you can start building applications with data from the sandbox.