Setting Up a Remote Authorization Server

How to authorize your own cards. | Enterprise

This procedure describes the specifications for communications between a client's remote authorization server and Rapyd.

Create a secure server and build software that handles data communication according to Rapyd's specifications.
Contact Customer Support and run all required tests.
Provide the URL of your remote authorization server and the BIN numbers of the cards to be processed on the remote server.

When your server passes Rapyd's tests, Rapyd will configure your account so that all transactions on cards issued through Rapyd's issuing platform are routed to your remote authorization server.

For more information on how the transactions are authorized, see the following:

Authorizing a Card Transaction Remotely - Follows a successful card transaction through the remote authorization process.

Required Message Formats

Messaging between Rapyd and your remote authorization server is done over the HTTPS protocol. The messages are in JSON format, as specified below.

Authorization Request

Request Headers

Rapyd’s request to the remote authorization server contains the standard request headers. Headers are required for both the production platform and the sandbox, however they are not required in the response from your remote authorization server.

The authorization request is sent from Rapyd to the remote authorization server operated by the client. It has the following fields:

Name	Type	Description
amount	number	Amount of the transaction in currency units defined in `currency`.
authorization_id	string	ID of the transaction authorization request. String starting with cardauth_.
card_id	string	ID of the card on the Rapyd platform. String starting with card_.
contact_id	string	ID of the wallet contact on the Rapyd platform. String starting with cont_.
created_at	number	Time of the transaction, in Unix time.
currency	string	Currency of the transaction. Three-letter ISO 4217 code.
pos_info	object	Describes the location where the card was used. Contains the following fields: card_holder_presence - Boolean - Indicates whether the cardholder was physically present for the transaction. identification_code - string - Identifier for the point of sale where the card was used. mcc - string - Visa merchant category code. name_and_location - string - Name and address of the seller. terminal_id - string - ID of the terminal where the card was swiped.
status	string	Status of the request.
type	string	For an authorization request: authorization

Example Authorization Request

Authorization Request

{
    "amount": 12.96,
    "authorization_id": "cardauth_874618744ffs3r452",
    "card_id": "card_874618744ffs3r452",
    "contact_id": "cont_874618744ffs3r452",
    "created_at": 1352316334,
    "currency": "USD",
    "pos_info": {
        "card_holder_presence": true,
        "identification_code": "GYUI",
        "mcc": "5812",
        "name_and_location": "RITE AID, 2244 CORNER ST., MEXICO CITY",
        "terminal_id": "7865"
    },
    "status": "PENDING",
    "type": "authorization"
}

Authorization Response

When the remote authorization server receives the authorization request, it must return a response with the following fields:

Name	Type	Description
authorization_id Required	string	ID of the transaction authorization request. Same as the `authorization_id` in the request.
response_code Required	string	Response code, defined in the ISO 8583-1987 standard. Two digits.
auth_code	string	Alphanumeric code defined by the client. Optional.

Example Authorization Response

Authorization Response

{
    "authorization_id": "cardauth_874618744ffs3r452",
    "response_code": "00",
    "auth_code": "1A2B3C"
}

Transaction Completed Webhook

When the card network reports that the transaction succeeded, Rapyd sends a webhook to the client with the following fields:

Name	Type	Description
authorization_id	string	ID of the transaction authorization request. Same as the `authorization_id` in the request.
created_at	number	Time of the authorization, in Unix time.
status	string	COMPLETED
type	string	authorization

Example Transaction Completed Webhook

Transaction Completed Webhook

{
    "type": "authorization",
    "authorization_id": "cardauth_43809d47fd8s7f89df",
    "created_at": 1352316334,
    "status": "COMPLETED"
}

Transaction Reversed Webhook

When the the transaction cannot be completed due to a communications failure or other reason, the transaction is reversed. When this occurs, Rapyd returns a webhook to the client with the following fields:

Name	Type	Description
authorization_id	string	ID of the transaction authorization request. Same as the `authorization_id` in the request.
currency	string	Currency of the reversal. Three-letter ISO 4217 code.
created_at	number	Time of the reversal, in Unix time.
reversed_amount	number	Amount of the reversal. Can be less than the amount of the original transaction.
reversed_authorization_id	string	ID of the transaction reversal. String starting with cardauth_.
status	string	REVERSED
type	string	authorization

Example Transaction Reversed Webhook

Transaction Reversed Webhook

{
    "authorization_id": "cardauth_43809ruifd8s7f89sdf",
    "currency": "USD",
    "created_at": 1352316334,
    "reversed_amount": 3.45,
    "reversed_authorization_id": "cardauth_874618744ffs3r452",
    "status": "REVERSED",
    "type": "authorization"
}

In this section:

Documentation

Setting Up a Remote Authorization Server

Required Message Formats

Authorization Request

Request Headers

Example Authorization Request

Authorization Response

Example Authorization Response

Transaction Completed Webhook

Example Transaction Completed Webhook

Transaction Reversed Webhook

Example Transaction Reversed Webhook

Search results