Skip to main content

Documentation

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.

  1. Create a secure server and build software that handles data communication according to Rapyd's specifications.

  2. Contact Customer Support and run all required tests.

  3. 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:

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

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"
        }
        

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"
        }
        

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"
        }
        

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"
        }