For developers

Card payments

2min

The first step to working with Cross River APIs is to submit a request for Sandbox access.

Make sure you fill in all the relevant fields. The more accurate the information you give us at this stage, the faster you'll be onboarded into our systems.

Include:

  • Your full name
  • The name of the company you work for/represent.
  • The URL of the official company website.
  • The location/address of your company.
  • A working telephone number including international dialing code.
  • Your static public IP address in IPv4 format (not hexadecimal format).

IMPORTANT You must have an allowlisted static public IP to access our products. Your internal IT department should be able to provide you with your static IP. For more information on static IPs see here.

Once we allowlist your static IP, we send you 2 encrypted emails with your credentials. One email with your client_id and one email with your client_secret. Your relationship manager will give you your partner_id.

We'll also send you an encrypted email with your P2C credentials.

The request and response models for Cross River products are available in our Swagger.

OAuth 2.0 is a popular protocol for authorization. This controls entry to our system and ensures that only authorized entities can access our APIs and other protected resources. The information you enter into our authentication system is confidential and can never be accessed from any other Cross River applications.

Access Cross River APIs

Our system authenticates machine clients and authorizes them to talk to our APIs.

Authenticate your identity

The Cross River Integration Team provides you with a client_id and a client_secret that you use when requesting an access token. You can use a web-based tool, like Postman, to send API requests.

HTTP request components

HTTP component

Attribute

Description

Endpoint

POST /connect/token

Endpoint for retrieving an access token.

Header

content-type

application/x-www-form- urlencoded

Body

grant_type

This field will always have a value of client_credentials

Secrets aren't recoverable by CR. If you lose a secret, a new one must be generated.

Body

client_id

The unique identifier for a client.

Body

client_secret

An encrypted string of characters used to sign and validate ID tokens.

Important: Don’t commit your secrets into source control.

Secrets aren't recoverable by CR. If you lose a secret, a new one must be generated.

Body

scope

A specific range or a limited set of services that a user can access with an access token.

- If the required scope is missing, the subsequent API call will be returned as forbidden (403).

- If a scope isn't specified, the token returned will contain all scopes associated with your credentials.

Note: Multiple scopes can be sent in the same request by adding a space between the name of each scope.

For example: 'scope=scope1 scope2 scope3'

Sample call for an access token in cURL

Sample access token in cURL


Sample call for an access token in Postman

Document image


Successful authentication and access token returned

When you've successfully authenticated, an access_token will be returned to you. This access token allows you to send information securely as a JSON object for use in our APIs. Add this token to the header of your API calls.

IMPORTANT Make sure to protect your token. Don’t log it. Anyone who steals your token can impersonate your client for the lifetime of the token.

Response attributes

access_token

A digitally signed JSON web token (JWT) sent from the oAuth server that allows access to specific Cross River resources.

scope

A range of services that a user can access.

expires_in

The amount of time until the token expires.

  • Our Integration Team will inform you of the expiration time or you can decode your encrypted access token as well.
  • We recommend that you retrieve a new access token a short time before the old token is set to expire.
  • Reuse tokens for their entire lifespan rather than get a new token for each call to the same protected resource (API).

IMPORTANT: Make sure to never decode your token on a publicly hosted website.

token_type

Bearer token.

Sample Postman access token return

If the authentication is successful, the Status code is OK.

Document image


URLs for our sandbox and production environments

Sandbox URL: https://oauthtest.crbnj.net/connect/token

Production URL: https://oauth.crbnj.net/connect/token

Troubleshooting

You can test the authorization and authentication into our systems with this endpoint, GET /api/SignupCard/TestOauth. If the authentication token is valid, it will return a 200. If the authentication token isn't valid, it will return a 401.

If you can't get a bearer token and you haven't received one in the past:

  • Confirm the URL.
  • Check that the client_id and client_secret are typed correctly. They are case sensitive.
  • Check your client_id and client_secret against the one you received.
  • Make sure there are no network or allowlist issues.

Contact our Integration Team if your account is locked as a result of 3 incorrect log in attempts.

To start working with Card Payments, make sure you have:

  • API credentials
  • Signed up the card you are pushing funds to
  • requestId - your unique reference ID
  • cardToken - the token you received when you registered the card
  • The dollar amount to send
  • Enough funds in your account
  • The name of the person or organization originating the push transaction

We also recommend that you register for the relevant webhook events.

You can now make your first Push to Card payment.

Card Payments has its own collection of APIs that require a separate authentication key and integration.

Status Page

To see a list of upcoming releases, monitor current API status, view incident reports, or get notified of scheduled maintenance, visit our status page and subscribe to alerts.



Updated 28 Jan 2025
Did this page help you?
PREVIOUS
Send your first API
NEXT
Register
Docs powered by Archbee