---
title: "Setting Up a Remote Authorization Server"
source_url: https://docs.rapyd.net/en/setting-up-a-remote-authorization-server.html
lang: en
---

# 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:

- [Authorizing a Card Transaction Remotely](https://docs.rapyd.net/en/authorizing-a-card-transaction-remotely.md "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

> **Note:**
>
> Rapyd’s request to the remote authorization server contains the standard request headers. Headers are required for both the  [production](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_production "Production") platform and the [sandbox](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_sandbox "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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/build-with-rapyd/reference/webhooks) 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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "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"
      }
      ```