Authorization Requests

Deprecated

This is [an obsolete version](https://www.unit.co/docs/api/#deprecations) of the programmatic authorization flow. Details of the new implementation (that can support concurrent authorization requests, improving performance and stability) can be found here. The old webhook based version will be available through 2023. We highly recommend migrating to the new version.

When an end-customer makes a purchase using a debit card, Unit creates an authorization request, allowing you to approve or decline the purchase. We refer to this process as Programmatic authorization of card use.

Restricting payments to certain types of institutions / services
Moving funds between accounts of the customer in real time to meet the authorization request amount.

note

Programmatic authorization of card use is not enabled by default. Please contact Unit to enable it.

Programmatic authorization of card use

The Programmatic authorization of card use includes the following steps:

An authorizationRequest.pending webhook event is sent by Unit.
You can then approve or decline the authorization request via an API call (see below).
If you do not approve or decline the authorization request within 2 seconds, Unit will approve or decline it according to the default that is defined for you on Unit's settings (which can be changed any time by contacting Unit).
The response from the approve operation will include the final authorization request status. Approving an authorization request may still result in a Declined status for different reasons. For example, at this stage Unit will check the balance on the account, and may decline the authorization due to insufficient funds.
Unit will send an authorizationRequest.approved or authorizationRequest.declined webhook event based on the final approval status.
If an authorization's amount changes the whole process will restart from stage (1).

note

In order to test the programmatic authorization of card use in Sandbox, you may take advantage of the ability to simulate a Card Purchase Authorization Request, Card Transaction Authorization Request or ATM Authorization Request.

Get by Id

Get an authorization request resource by id.

Verb	`GET`
Url	`https://api.s.unit.sh/authorization-requests/{id}`
Required Scope	`authorization-requests`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	PurchaseAuthorizationRequest / CardTransactionAuthorizationRequest / AtmAuthorizationRequest	Authorization Request resource.

curl -X GET 'https://api.s.unit.sh/authorization-requests/1' \
-H "Authorization: Bearer ${TOKEN}"

List

List authorization requests. Filtering and paging can be applied.

Verb	`GET`
Url	`https://api.s.unit.sh/authorization-requests`
Required Scope	`authorization-requests`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources.
page[offset]	integer	0	Optional. Number of resources to skip.
filter[accountId]	string	(empty)	Optional. Filters the results by the specified account id.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[merchantCategoryCode][]	Integer	(empty)	Optional. Filter result by their 4-digit ISO 18245 merchant category code (MCC).
filter[fromAmount]	Integer	(empty)	Optional. Filters the result that have an amount that is higher or equal to the specified amount (in cents). e.g. `5000`
filter[toAmount]	Integer	(empty)	Optional. Filters the result that have an amount that is lower or equal to the specified amount (in cents). e.g. `7000`

curl -X GET 'https://api.s.unit.sh/authorization-requests?page[limit]=20&page[offset]=0' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of PurchaseAuthorizationRequest / CardTransactionAuthorizationRequest / AtmAuthorizationRequest	Array of authorization request resources.

Example Response:
{
  "data": [
    {
      "type": "purchaseAuthorizationRequest",
      "id": "1",
      "attributes": {
        "createdAt": "2021-06-22T13:39:17.018Z",
        "amount": 2500,
        "status": "Approved",
        "partialApprovalAllowed": false,
        "approvedAmount": 2500,
        "merchant": {
          "name": "Apple Inc.",
          "type": 1000,
          "category": "",
          "location": "Cupertino, CA",
          "id": "311204598883"
        },
        "recurring": false
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "account": {
          "data": {
            "type": "account",
            "id": "10001"
          }
        },
        "card": {
          "data": {
            "type": "card",
            "id": "7"
          }
        }
      }
    },
    {
      "type": "cardTransactionAuthorizationRequest",
      "id": "2",
      "attributes": {
        "createdAt": "2021-06-22T13:41:01.379Z",
        "amount": 2500,
        "status": "Pending",
        "partialApprovalAllowed": false,
        "merchant": {
          "name": "Apple Inc.",
          "type": 1000,
          "category": "",
          "location": "Cupertino, CA",
          "id": "311204598883"
        },
        "recurring": false
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "account": {
          "data": {
            "type": "account",
            "id": "10001"
          }
        },
        "card": {
          "data": {
            "type": "card",
            "id": "7"
          }
        }
      }
    }
  ]
}

Approve

Approves a pending authorization request.

Verb	`POST`
Url	`https://api.s.unit.sh/authorization-requests/:id/approve`
Required Scope	`authorization-requests-write`
Data Type	`approveAuthorizationRequest`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
amount	integer	Optional. The approved amount (in cents). Can only be specified if the authorization request's `partialApprovalAllowed` is set to `true`.
fundingAccount	string	Optional. The id of an alternate account (either the customer's or another's) that should be used for funding the transaction. Please contact Unit to enable this feature.
tags	object	Optional, See Tags. The specified tags will be inherited by the resulting authorization and transaction resources.

Example Request:
curl -X POST 'https://api.s.unit.sh/authorization-requests/1/approve'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "approveAuthorizationRequest",
    "attributes": {
      "amount": 5000
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	PurchaseAuthorizationRequest / CardTransactionAuthorizationRequest / AtmAuthorizationRequest	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "purchaseAuthorizationRequest",
    "id": "1",
    "attributes": {
      "createdAt": "2021-06-22T13:39:17.018Z",
      "amount": 2500,
      "status": "Approved",
      "partialApprovalAllowed": true,
      "approvedAmount": 2500,
      "merchant": {
        "name": "Apple Inc.",
        "type": 1000,
        "category": "",
        "location": "Cupertino, CA",
        "id": "311204598883"
      },
      "recurring": false
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "account": {
        "data": {
          "type": "account",
          "id": "10001"
        }
      },
      "card": {
        "data": {
          "type": "card",
          "id": "7"
        }
      }
    }
  }
}

Decline

Declines a pending authorization request.

Verb	`POST`
Url	`https://api.s.unit.sh/authorization-requests/:id/decline`
Required Scope	`authorization-requests-write`
Data Type	`declineAuthorizationRequest`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
reason	string	The reason for declining the authorization request. One of `AccountClosed`, `CardExceedsAmountLimit`, `DoNotHonor`, `InsufficientFunds`, `InvalidMerchant`, `ReferToCardIssuer`, `RestrictedCard`, `TransactionNotPermittedToCardholder`.

Example Request:
curl -X POST 'https://api.s.unit.sh/authorization-requests/1/decline'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "declineAuthorizationRequest",
    "attributes": {
      "reason": "InsufficientFunds"
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	PurchaseAuthorizationRequest / CardTransactionAuthorizationRequest / AtmAuthorizationRequest	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "purchaseAuthorizationRequest",
    "id": "1",
    "attributes": {
      "createdAt": "2021-06-22T13:39:17.018Z",
      "amount": 2500,
      "status": "Declined",
      "partialApprovalAllowed": true,
      "declineReason": "InsufficientFunds",
      "merchant": {
        "name": "Apple Inc.",
        "type": 1000,
        "category": "",
        "location": "Cupertino, CA",
        "id": "311204598883"
      },
      "recurring": false
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "account": {
        "data": {
          "type": "account",
          "id": "10001"
        }
      },
      "card": {
        "data": {
          "type": "card",
          "id": "7"
        }
      }
    }
  }
}

Authorization Requests

Deprecated

Programmatic authorization of card use​

Get by Id​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Approve​

Attributes​

Response​

200 OK​

Decline​

Attributes​

Response​

200 OK​

Programmatic authorization of card use

Get by Id

Response

200 OK

List

Query Parameters

Response

200 OK

Approve

Attributes

Response

200 OK

Decline

Attributes

Response

200 OK