Skip to main content

Cards: Authorization Requests

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 purchases.

  • 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 purchases is not enabled by default. Please contact Unit to enable it.

Programmatic authorization of card purchases#

The Programmatic authorization of card purchases includes the following steps:

  1. An authorizationRequest.pending webhook event is sent by Unit.
  2. You can then approve or decline the authorization request via an API call (see below).
  3. 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).
  4. 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.
  5. Unit will send an authorizationRequest.approved or authorizationRequest.declined webhook event based on the final approval status.
note

In order to test the programmatic authorization of card purchases in Sandbox, you may take advantage of the ability to Simulate a Card Purchase Authorization Request.

Get by Id#

Get an authorization request resource by id.

VerbGET
Urlhttps://api.s.unit.sh/authorization-requests/{id}
Required Scopeauthorization-requests

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataPurchaseAuthorizationRequestAuthorization 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.

VerbGET
Urlhttps://api.s.unit.sh/authorization-requests
Required Scopeauthorization-requests

Query Parameters#

NameTypeDefaultDescription
page[limit]integer100Maximum number of resources that will be returned. Maximum is 1000 resources.
page[offset]integer0Number 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.
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#

FieldTypeDescription
dataArray of PurchaseAuthorizationRequestArray 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"        },        "recurring": false      },      "relationships": {        "customer": {          "data": {            "type": "customer",            "id": "10000"          }        },        "account": {          "data": {            "type": "account",            "id": "10001"          }        },        "card": {          "data": {            "type": "card",            "id": "7"          }        }      }    },    {      "type": "purchaseAuthorizationRequest",      "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"        },        "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.

VerbPOST
Urlhttps://api.s.unit.sh/authorization-requests/:id/approve
Required Scopeauthorization-requests-write
Data TypeapproveAuthorizationRequest

Attributes#

NameTypeDescription
amountintegerOptional. The approved amount (in cents). Can only be specified if the authorization request's partialApprovalAllowed is set to true.
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#

FieldTypeDescription
dataPurchaseAuthorizationRequestThe 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"      },      "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.

VerbPOST
Urlhttps://api.s.unit.sh/authorization-requests/:id/decline
Required Scopeauthorization-requests-write
Data TypedeclineAuthorizationRequest

Attributes#

NameTypeDescription
reasonstringThe 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#

FieldTypeDescription
dataPurchaseAuthorizationRequestThe 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"      },      "recurring": false    },    "relationships": {      "customer": {        "data": {          "type": "customer",          "id": "10000"        }      },      "account": {        "data": {          "type": "account",          "id": "10001"        }      },      "card": {        "data": {          "type": "card",          "id": "7"        }      }    }  }}