Sending API requests and receiving responses

At Cross River, we have a robust set of APIs spanning our suite of products. To access our APIs and try them out in our sandbox, contact customer support to get started. Our Integrations Team will then lead you through the steps to use our sandbox.

API requests and responses

When you call an API, you have sent a request. The answer you receive back is the response.

Resource/object

A resource (object) is the category of information that you want to receive information for, via APIs. For example, in our P2C product, a card and a transaction are resources, and in our lending product, a loan is a resource.

Endpoints and methods

An endpoint is the URL address of an API that you want to retrieve. You can retrieve an endpoint by using a method. The method is the prefix you add to your endpoint to send the relevant API request.

The methods we use for our APIs are:

• GET
  Send a GET request to retrieve resource information. A GET request never has a body.
• POST
  Send a POST request to add or create a resource.
• PUT
  Send a PUT request to update or fix resource information.
• DELETE
  Send a DELETE request to delete or cancel a resource.
• PATCH
  Send a PATCH request to update or fix a smaller scope of resource information.

Parameters

To narrow down the responses of an API, you can pass parameters into an endpoint. When added to an endpoint, parameters determine the type of action you want to take, and they affect the response returned to your request.

When you pair a parameter with a method in your endpoint, the response has information relevant to that endpoint that has been narrowed down with that parameter.

There are 3 types of parameters:

• Path
  A path parameter can be added to a URL endpoint to return a specific response. The path parameter is added to the URL in curly brackets ({ }) and follows a backslash (/).
  For example, if you want to retrieve specific information on an account, you can add /{accountnumber} to the URL.
  When your API includes curly brackets, a path parameter is required.

• Body
  Body parameters are the data included in the body of an API, and the information they represent can be changed. The body of the request and response messages are called payloads.

• Query
  A query parameter narrows down and filters the results of your request based on the information you are requesting. The query parameter is added to the URL and follows a question mark (?). Only GET calls use query parameters.

Use cases

Retrieve details about a specific debit card
To retrieve details about a specific debit card, call GET /api/Card/{cardToken}. Add the cardToken into the curly brackets. Only that card information is returned.

Retrieve a list of debit cards that were added to the system between specific dates
To retrieve a list of debit cards that were added to the system between specific dates, add the query parameters dateAddedTo and dateAddedFrom to the request GET /api/Card. Only debits cards between those specific dates are returned in the response.

Add a debit card to P2C
To add a debit card to P2C, call POST /api/Card. Add required (and optional) details to the request body and send the call. The response returns information confirming that the debit card was added.

To update a webhook registration
To update a webhook registration, call PUT /api/WebhookRegistrations/{registrationId}. Add the registrationId for the webhook into the curly brackets to retrieve that specific webhook registration. In the body of the payload, make the necessary changes to the webhook registration.

To deactivate a webhook registration
To deactivate a webhook registration, call DELETE /api/WebhookRegistrations/{registrationId}. Add the registrationId for the webhook into the curly brackets to deactivate just that webhook registration.

Putting it all together

When you're ready to start trying out our APIs and you've contacted customer support, they will send you a client ID and a password. After you're authorized into our system with the credentials, you'll receive an access token (a bearer token). Add the access token to your header, and you can then start calling our APIs.

You can send API requests using the command line with a tool such as cURL or by using a tool with a graphical user interface (GUI), such as Postman.

With any tool that you use, you have to add information to the endpoint of a call.