Allawee API Reference

The Allawee API lets you interact with Allawee resource objects like cards, customers, webhook, events, accounts, simulation. Allawee API is RESTful. You can use it with REST clients like Postman, in your client-side code, in your server-side code, or from your command line with CURL. Every request you make needs an Authorization token.

There are two base URLs for requests:

https://api.allawee.com: This is the base url for all request that doesn’t share sensitive customer data
https//secure.allawee.com: This is the base url for all requests that share sensitive customer data like Reset Card Pin

Response Format

The Allawee API endpoints provide responses in JSON, formatted for your easy use. You can consume the API the same way you would with any other RESTful API. There are three uppermost attributes you can access in the endpoints:

code
data
metadata

ATTRIBUTESDATA TYPE
DESCRIPTION
codestring
Lets you know whether your request was successful or not.
dataobject
Provides the response object to your request
metadataobject
Provides additional infromation about the response

Example Response

{
  "code": "success",
  "data": [
    {
      "type": "physical",
      "status": "inactive",
      "currency": "NGN",
      "details": {
        "last4": "8058",
        "expiry": "02/26",
        "cardHolderName": "John Doe"
      },
      "createdAt": "2023-02-22T12:51:04.832Z",
      "updatedAt": "2023-02-23T15:55:27.715Z",
      "program": "cp.2tQhBbJUiFr5gpA8e",
      "controls": {
        "allowedCategories": ["betting", "flight-ticket", "hospitality"],
        "allowedChannels": ["atm", "pos", "online"],
        "spendingLimits": [
          {
            "amount": 500000,
            "interval": "daily"
          }
        ]
      },
      "customer": "cus.2tR4ahZppUVuQsJbt",
      "metadata": {
        "meta": "1234"
      },
      "id": "c.2tQhCwZKuPWqySW51"
    }
  ],
  "metadata": {
    "hasMore": true
  }
}

Testing

When using the Allawee API, you may need to test your implementation before you go live. Ensure your secret key is set to test mode and get familiar with using the API before integration to live.

Errors

When the Allawee API processes a request, it will return a success or failure response to you. A successful response will return a code of “SUCCESS”. Any other response code is a failure, although the code may vary depending on why the request failed.

Response Codes

You can use the response code you receive to determine if your request was properly processed and your response is what you expect. If the request is unsuccessful, the response code can let you know what went wrong.

RESPONSE CODEDATA TYPE
DESCRIPTION
SUCCESSstring
Your request was successful.
AUTHORIZATION_REQUIREDstring
You did not include an authentication token in your request.
INVALID_AUTHORIZATION_KEYstring
The authentication token you used for your request is invalid.
INVALID_AUTHORIZATION_TYPEstring
Ensure that you are using “Bearer ” before your authentication token in your request.
MALFORMED_AUTHORIZATION_KEYstring
There are missing elements in your authentication token.
APPLICATION_TIMEOUTstring
The Allawee API took too long to process your request.
REQUEST_TIMEOUTstring
There is a network or service problem preventing your request from being completed.
SERVICE_UNAVAILABLEstring
The server is currently unavailable.
TRIAL_ENDEDstring
Your trial has ended.

Endpoints

Data provided by the Allawee API is organised based on what you need. Each kind of data has its own endpoint.

Customers

The Customers API lets you Create a customer, Fetch customers, Update info on your customers and perform various actions on them.

ARGUMENTREQUIRED
DESCRIPTION
customersrequired
The id of the customers to perform the action on.

Create Customers

This section assumes that you have gotten your authentication token. Use your token to make a POST request to the Create customer endpoint like so:

Endpoint

To create a customer, make a POST request to https://api.allawee.com/customers.

The data in the payload of your request should include:

ATTRIBUTEDATA TYPE
DESCRIPTION
namestring
Your customer’s name.
referencestring
To identify your customer
claimsarray[object]
individualInformation
- firstNamestring
  The first name of the customer
- middleNamestring
  The middle name of the customer
- lastNamestring
  The last name of the customer
- titlestring
  The title of the customer
- genderstring
  The gender of the customer
- emailstring
  email of the customer
- phoneNumberstring
  phone number of the customer
- dateOfBirthstring
  date of birth of the customer
- countryCodestring
  The country code of the customer
- individualAddress[object]
  The address of the individual
  citystring
  The city of the customer
  statestring
  The state of the customer
  countryCodestring
  The country code of the customer
  lineOnestring
  The address of the customer
  lineTWo(optional)string
  The address of the customer
  postalCodestring
  The postal code of the city of the customer
- individualIdentity[object]
  The bank identification number of the customer
  typestring
  BVN(Default)
  idnumber
  The BVN number of the customer
  issuingCountrystring
  The issuing country of the customer
verificationarray[object]
[object]
- typestring
  The type of the account of the customer
- statusstring
  The status of the customer
metadata[object]
[object]

If your request is successful, you will get a response with a 200 status code and a data field with information on your cards. Your response should look something like this.

Any other status code besides 200 is an error response. You can check our error responses to determine how you want to handle errors.

Example Customer Request

curl --request POST \
  --url https://api.allawee.com/customers \
  --header 'Authorization: Bearer token' \
  --data '{
    "name": "Chiroma Adekunle",
    "reference": "123469",
    "type": "individual",
    "claims": {
        "individualInformation": {
          "firstName": "Chiroma"
          "middle": "Chukwuma",
          "lastName": "Adekunle",
          "title": "Mr",
          "gender": "M",
          "email": "[email protected]",
          "phoneNumber": "+2348111110000",
          "dateOfBirth": "1996-2-14",
          "nationalityCode": "NG"
        },
       "individualAddress": {
          "city": "Yaba",
          "state": "NG-LA",
          "countryCode: "NG",
          "lineOne": "No 7 commercial road",
          "lineTWo": "34 oladoyinbo street",
          "postalCode": "100001"
        },
        "individualIdentity": {
          "type": "bvn",
          "id": "22348901673",
          "issuingCountry": "NG"
        }
    },
    "verification": [
        {
          "type": "tier-2",
          "status": "verified"
        }
    ],
    "metadata": {
      "userId": 11223
    }
}'

Example Cards Response

{
  "code": "success",
  "data": {
    "name": "Chiroma C. Adekunle",
    "reference": "123469",
    "type": "individual",
    "status": "active",
    "claims": {
      "individualInformation": {
        "firstName": "Chiroma",
        "lastName": "Chukwuma",
        "middleName": "Adekunle",
        "email": "[email protected]",
        "phoneNumber": "+2348111110000",
        "title": "Mr.",
        "gender": "M",
        "dateOfBirth": "1996-02-14",
        "nationalityCode": "NG"
      },
      "individualAddress": {
        "city": "Yaba",
        "state": "NG-LA",
        "countryCode": "NG",
        "addressLineOne": "No 7 commercial road",
        "addressLineTwo": "34 oladoyinbo street",
        "postalCode": "100001"
      },
      "individualIdentity": {
        "type": "bvn",
        "id": "22348901673",
        "issuingCountry": "NG"
      }
    },
    "verifications": [
      {
        "type": "tier-2",
        "status": "verified"
      }
    ],
    "metadata": {
      "userId": 11223
    },
    "createdAt": "2023-02-26T23:59:06.213Z",
    "updatedAt": "2023-02-26T23:59:06.213Z",
    "id": "cus:96ed7288db297c82b214e841",
    "object": "customer"
  }
}

Get Customer

The Get customer endpoint allows you get specific details or information about a customer


GET	customers/{id}

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
Your customer id.

Update Customers

The Update Customers endpoint allows you update the data of a customer.

This section assumes that you have gotten your authentication token. Use your token to make a PATCH request to the Update customer endpoint like so:

Endpoint

To update a customer, make a PUT request to https://api.allawee.com/customers/{id}.

Response

The data in the payload of your request should include:

ATTRIBUTEDATA TYPE
DESCRIPTION
namestring
Your customer’s name.
referncestring
To identify your customer.
claimsarray[object]
individualInformation
- middleNamestring
  The middle name of the customer
- lastNamestring
  The last name of the customer
- titlestring
  The title of the customer
- genderstring
  The gender of the customer
- emailstring
  email of the customer
- phoneNumberstring
  phone number of the customer
- dateOfBirthstring
  date of birth of the customer
- individualAddress[object]
  The address of the individual
  citystring
  The city of the customer
  statestring
  The state of the customer
  countryCodestring
  The country code of the customer
  lineOnestring
  The address of the customer
  lineTWo(optional)string
  THe address of the customer
  postalCodestring
  The postal code of the city of the customer
- individualIdentity[object]
  The bank identification number of the customer
  typestring
  BVN(Default)
  idnumber
  The BVN number of the customer
  issuingCountrystring
  The issuing country of the customer
verificationarray[object]
[object]
- typestring
  The type of the account of the customer
- statusstring
  The status of the customer
metadata[object]
[object]

If your request is successful, you will get a response with a 200 status code and a data field with information on your customers. Your response should look something like this.

Any other status code besides 200 is an error response. You can check our error responses to determine how you want to handle errors.

Example Customer Request

curl --request PUT \
  --url https://api.allawee.com/customers/{id} \
  --header 'Authorization: Bearer token' \
  --data '{
    "name": "Chiroma Adekunle",
    "reference": "123469",
    "claims": {
        "individualInformation": {
             "middle": "Chiroma",
             "lastName": "Adekunle",
             "title": "Mr",
             "gender": "M",
             "email": "[email protected]",
             "phoneNumber": "+2348111110000",
             "dateOfBirth": "1996-2-14"
        },
        "individualAddress": {
            "city": "Yaba",
            "state": "NG-LA",
            "countryCode: "NG",
            "lineOne": "No 7 commercial road",
            "lineTWo": "34 oladoyinbo street",
            "postalCode": "100001"
        },
        "individualIdentity": {
            "type": "bvn",
            "id": "22348901673",
            "issuingCountry": "NG"
        }
    },
    "verification": [
        {
            "type": "standard-account",
            "status": "verified"
        }
    ],
    "metadata": {
      "userId": 2345
    }
}'

Example Cards Response

{
  "code": "success",
  "message": "Request Successful",
  "data": {
    "name": "Chiroma C. Adekunle",
    "type": "individual",
    "claims": {
      "individualInformation": {
        "firstName": "Chiroma",
        "lastName": "Chukwuma",
        "middleName": "Adekunle",
        "email": "[email protected]",
        "phoneNumber": "+2348111110000",
        "title": "Mr.",
        "gender": "M",
        "dateOfBirth": "1996-02-14",
        "nationalityCode": "NG"
      },
      "individualAddress": {
        "city": "Yaba",
        "state": "NG-LA",
        "countryCode": "NG",
        "addressLineOne": "No 7 commercial road",
        "addressLineTwo": "34 oladoyinbo street",
        "postalCode": "100001"
      },
      "individualIdentity": {
        "type": "bvn",
        "id": "22348901673",
        "issuingCountry": "NG"
      }
    },
    "verifications": [
      {
        "type": "standard-account",
        "status": "verified"
      }
    ],
    "metadata": {
      "userId": 2345
    },
    "id": "cus:96ed7288db297c82b214f901"
  }
}

Cards

The Cards API lets perform various action on the cards.

ARGUMENTREQUIRED
DESCRIPTION
cardrequired
The unique identifier of the card object.

Get All Cards

Getting all cards will show you all cards under your account.


GET	/cards

ATTRIBUTEDATA TYPE
DESCRIPTION
limitnumber
A limit on the number of card objects to be returned.
sortstring
Sort by state
beforestring
you can use “before” as a cursor, which is the object ID that indicates the end of the previous page, enabling you to fetch the preceding page of the list by specifying it in your next call.
afterstring
in order to navigate through a list of objects using pagination, you can use “after” as a cursor, which is the object ID indicating the start of the next page, and by including it in your next call, you can fetch the next page of the list.

Link Card

Linking a card links a customer and pan to a card. This endpoint requires the secure base url https://secure.allawee.com


POST	/cards/link

ATTRIBUTEDATA TYPE
DESCRIPTION
panstring
The pan of the card.
customerstring
The card id
controlsobject
The control features to be set on the card’s spending.
- allowedCategories[Array]
  The categories of spending that the card custodian can carry out using the card.
- blockedCategories[Array]
  The categories of spending that the custodian should not carry out with the card.
- spendingLimits[Array]
  Limits that the card custodian should not exceed.
  amountnumber
  The amount the custodian should not spend beyond, in the lowest unit of the currency.
  intervalstring
  The interval for the spending limit amount; it may be DAILY, WEEKLY, or MONTHLY.

Example Request

curl --request POST \
  --url https://secure.allawee.com/cards/link \
  --header 'Authorization: Bearer token' \
  --data '{
    "pan": "5061462447400676038",
    "customer": "cus.2tPFwHj3XnQhzyWCy",
    "controls": {
        "allowedCategories": [
            "flight-ticket"
        ],
        "blockedCategories": [
            "betting"
        ],
        "spendingLimits": [
            {
                "amount": 1000,
                "interval": "monthly"
            }
        ]
    },
    "metadata": {
        "userId": "2345"
    }
}'

Example

{
  "code": "success",
  "data": {}
}

Activate Card

Activating a card allows the card holder to use that card. This involves changing the card’s default pin. This endpoint requires the secure base url https://secure.allawee.com


POST	/cards/{id}/activate

ATTRIBUTEDATA TYPE
DESCRIPTION
cvvstring
The 3 digits at the back of the card.
pinstring
The card’s new pin code.

Example Request

curl --request POST \
  --url https://secure.allawee.com/cards/{id}/activate \
  --header 'Authorization: Bearer token' \
  --data '{
    "cvv": "345",
    "pin": "5981"
}'

Example

{
  "code": "success",
  "data": {}
}

Update Card

The update card endpoint allows you to update the data of a particular card using the id.


PUT	/cards/{id}

idstring
The unique identifier of the card to update

Body params

controlsobject
The control features to be set on the card’s spending.
- allowedCategories[string]
  The categories of spending that the card custodian can carry out using the card.
- blockedCategories[string]
  The categories of spending that the custodian should not carry out with the card.
- allowedChannels[string]
  The channels of spending that the custodian can carry out using the card.
- blockedChannels[string]
  The channels of spending that the custodian should not carry out using the card.
- spendingLimits[object]
  Limits that the card custodian should not exceed.
  amountnumber
  The amount the custodian should not spend beyond, in the lowest unit of the currency.
  intervalstring
  The interval for the spending limit amount; it may be DAILY, WEEKLY, or MONTHLY.
  categorystring
  The category for the spending limit.
shippingAddressobject
The shipping address for the card’s delivery.
- citystring
  The city of the shipping address.
- statestring
  The state of the shipping address.
- countryCodestring
  The country of the shipping address, such as NG for Nigeria.
- lineOnestring
  The street and street number of the shipping address.
- postalCodestring
  The postal code of the shipping address.
- phoneNumberstring
  The phone number of the card owner/custodian.

Example Request

curl --request PUT \
  --url https://api.allawee.com/cards/{id} \
  --header 'Authorization: Bearer token' \
  --data '{
    "controls": {
        "allowedCategories": [
            "flight-ticket"
        ],
        "blockedCategories": [
            "betting"
        ],
        "allowedChannels": [
            "pos"
        ],
        "blockedChannels": [
            "online"
        ],
        "spendingLimits": [
            {
                "amount": 100000,
                "interval": "MONTHLY",
                "category": "food-groceries"
            }
        ]
    },
     "shippingAddress": {
        "address": {
          "city": "Lekki",
          "state": "NG-LA",
          "countryCode": "NG",
          "lineOne": "No 7, John Doe Close",
          "postalCode": "11041",
          "phoneNumber": "+2348111110000"
        },
     }
    "metadata": {
    "name": "John's travel card"
  }
}'

Example

{
  "code": "success",
  "data": {}
}

Block Card

Blocking one card temporarily prevents the card from being used for payments until it is unblocked.


POST	/cards/{id}/block

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
Unique identifier of the object.

Example Request

curl --request POST \
  --url https://api.allawee.com/cards/{id}/block \
  --header 'Authorization: Bearer token' \
  --data '{ }'

Example

{
  "code": "success",
  "data": {}
}

Unblock Card

You can unblock a card that has been blocked to begin making payments with it again.


POST	/cards/{id}/block

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
unique identifier of the card

Example Request

curl --request POST \
  --url https://api.allawee.com/cards/{id}/block \
  --header 'Authorization: Bearer token' \
  --data '{ }'

Example

{
  "code": "success",
  "data": {}
}

Terminate Card

Terminating a card permanently blocks the card, and refunds the card balance to the customer account.


DELETE	/cards/{id}

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
unique identifier of the card.

Example Request

curl --request DELETE \
  --url https://api.allawee.com/cards/{id} \
  --header 'Authorization: Bearer token' \
  --data '{ }'

Example

{
  "code": "success",
  "data": {}
}

Reset Card Pin

This endpoint lets you reset the pin of the card.


POST	/cards/{id}/reset-pin

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
Unique identifier of the card.

Example Request

curl --request POST \
  --url https://api.allawee.com/cards/{id}/reset-pin \
  --header 'Authorization: Bearer token' \
  --data '{
    "pin": "1234"
  }'

Example

{
  "code": "success",
  "data": {}
}

Fetch Card

Fetch Card lets you retrieve details about a specific card stored on the customer.


GET	/cards/{id}

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
Unique identifier of the card

Read Card Secrets

This endpoint lets you get the secrets of the card.


GET	/cards/{id}/secrets

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
Unique identifier of the card.

Example Request

curl --request GET \
  --url https://secure.allawee.com/cards/{id}/secrets \
  --header 'Authorization: Bearer token' \
  --data '{ }'

Example

{
  "code": "success",
  "data": {}
}

Create a virtual Card

This Create card endpoint allows you create a virtual card. Note that you have to create a virtual card program before creating a virtual card.

See here: Card Program

Endpoint

To create a virtual card, make a POST request to https://api.allawee.com/cards.

Body

The data in the payload of your request should include:

ATTRIBUTEDATA TYPE
DESCRIPTION
programstring
The virtual card program id
fxHashstring
The exchange rate hash.
debitCurrencystring
The type of currency to be debited.
amountnumber
The amount you want to fund the card with.
customerstring
The id of the customer
metadata[object]
meta key and value
- namestring
  The key for your metadata
- valuestring
  The value of the meta key

Create a virtual card

This section assumes that you have gotten your authentication token. Use your token to make a POST request to the Create a virtual card like so:

If your request is successful, you will get a response with a 200 status code and a data field with information on your virtual card. Your response should look something like this.

Any other status code besides 200 is an error response. You can check our error responses to determine how you want to handle errors.

Example Customer Request

curl --request POST \
  --url https://api.allawee.com/cards \
  --header 'Authorization: Bearer token' \
  --data '{
    "program": "c.prg.2u64yGpALXgHbqmjk",
    "fxHash": "002feeb17628ff7d10e4d55f445b89dbc2094429",
    "debitCurrencycurrency": "NGN",
    "amount": 1000,
    "customer": "cus.2ttTWz65gbPHDjR2B"
    "metadata": {
        "name": "Hilda USD card",
    },
 }'

Example Cards Response

{
  "code": "success",
  "data": {
    "type": "virtual",
    "network": "mastercard",
    "status": "inactive",
    "currency": "USD",
    "customer": "cus.2ttTWz65gbPHDjR2B",
    "program": "cp.2u64yGpALXgHbqmjk",
    "metadata": {
      "name": "Hilda USD card"
    },
    "details": {
      "cardHolderName": "Bachi  Hilda"
    },
    "createdAt": "2023-06-24T02:45:52.663Z",
    "updatedAt": "2023-06-24T02:45:52.663Z",
    "id": "c.2u6SXLG99Kq5a8TQ8",
    "object": "card"
  }
}

Fund virtual card

This allows you find a specific virtual card. The fund virtual card endpoint url https://api.allawee.com/cards/id/fund


POST	/cards/{id}/fund

ATTRIBUTEDATA TYPE
DESCRIPTION
fxHashstring
The exchange rate hash.
debitCurrencystring
The currency of the amount to be funded with
amountnumber
The amount you want to fund with

Example Request

curl --request POST \
  --url https://api.allawee.com/cards/id/fund \
  --header 'Authorization: Bearer token' \
  --data '{
    "fxHash": "b698273c866c4c7529f2c1f79a142799604842ca",
    "debitCurrency": "NGN",
    "amount": 500
}'

Example

{
  "code": "success",
  "data": {}
}

FX Rate

FX Rate allows you to fetch the exchange rate from USD to NGN and viceversa. The endpoint for FX rate url https://api.allawee.com/tools/fx/rate?from=NGN&to=USD


POST	/tools/fx/rate?from=NGN&to=USD

ATTRIBUTEDATA TYPE
DESCRIPTION
fromstring
The main currency
tostring
The currency to be exchanged with

Example Request

curl --request POST \
  --url https://api.allawee.com/tools/fx/rate?from=NGN&to=USD \
  --header 'Authorization: Bearer token' \
  --data '{
    "from": "NGN",
    "to": "USD"
}'

Example

{
  "code": "success",
  "data": {
    "from": "NGN",
    "to": "USD",
    "rate": 0.00131,
    "hash": "002feeb17628ff7d10e4d55f445b89dbc2094429",
    "lastUpdated": "2023-01-09T14:33:20.575Z"
  }
}

Webhooks

The Webhooks API lets you listen for events and perform actions when those events occur.

Create a Webhook

The create a webhook endpoint registers a url for the Allawee API to call when the chosen event occurs.


POST	webhooks

ATTRIBUTEDATA TYPE
DESCRIPTION
namestring
Any name of your choice to easily identity the webhook.
descriptionstring
A description of the webhook.
apiVersionstring
The Allawee API version you are subscribed to.
events[array]
An array of events you wish to listen for.
urlstring
The URL the Allawee API should make a post request to when the registered event occurs.

Example Webhook Creation Request

curl --request POST \
  --url https://api.allawee.com/webhooks \
  --header 'Authorization: Bearer token' \
  --data '{
  "name": "Card Authorization Webhook",
  "description": "This is my webhook, I like it a lot",
  "apiVersion": "2023-02-01",
  "events": [
    "card.authorization.request",
     "card.authorization.closed",
    "card.authorization.update",
  ],
  "url": "https://whsrv.mydomain.com/"
}'

Example

{
  "code": "success",
  "data": {}
}

Update Webhook

To Update your webhook, make a PUT request to https://api.allawee.com/webhooks/{id}


PUT	webhooks

ATTRIBUTEDATA TYPE
DESCRIPTION
namestring
Any name of your choice to easily identity the webhook.
descriptionstring
A description of the webhook.
apiVersionstring
The Allawee API version you are subscribed to.
events[string]
An array of events you wish to listen for.
urlstring
The URL the Allawee API should make a post request to when the registered event occurs.

Example Webhook Creation Request

curl --request PUT \
  --url https://api.allawee.com/webhooks/{id} \
  --header 'Authorization: Bearer token' \
  --data '{
  "name": "Card Authorization Webhook",
  "description": "This is my webhook, I like it a lot",
  "apiVersion": "2023-02-01",
  "events": [
    "card.authorization.request",
    "card.authorization.closed",
    "card.authorization.update",
    "card.transaction.created",
    "payment.completed"
  ],
  "url": "https://whsrv.mydomain.com/"
}'

Example

{
  "code": "success",
  "data": {}
}

Delete Webhook

The Delete Webhook API lets you deletes a webhook on your account.

Endpoint

To Delete a Webhook, make a DELETE request to https://api.allawee.com/webhook/{id}.

Response

The data in the payload of your request should include:

ARGUMENTREQUIRED
DESCRIPTION
webhookrequired
The id of the webhook to perform the action on.

Endpoint


DELETE	webhook/{id}

Example Request

curl --location --request DELETE 'https://api.allawee.com/webhook/{id}' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
}

Webhook Signing Key

The Webhook Signing Key API lets you get the secret signing key of the webhook created.

Endpoint

To get the Webhook Signing Key, make a GET request to https://api.allawee.com/webhooks/{id}/secret.

Query params

ARGUMENTREQUIRED
DESCRIPTION
webhookrequired
The id of the webhook to perform the action on.

Endpoint


GET	webhooks/{id}/secret

Example Request

curl --location --request GET 'https://api.allawee.com/webhooks/{id}/secret' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
}

Roll Webhook Signing Secret

The Roll Webhook Signing Secret API lets you roll the secret signing key of the webhook created.

Rolling the signing key on a regular basis helps ensure that any previously obtained keys are no longer valid, and that only authorized parties have access to the new key.

Endpoint

To get the Webhook Signing Key, make a POST request to https://api.allawee.com/webhooks/{id}/secret/roll.

Query params

ARGUMENTREQUIRED
DESCRIPTION
webhookrequired
The id of the webhook to perform the action on.

Endpoint


POST	webhooks/{id}/secret/roll

Example Request

curl --location --request POST 'https://api.allawee.com/webhooks/{id}/secret/roll' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
}

Card Programs

The Card Programs API allows you to create, control, update and scale a commercial card program for your users.

Create a Card Program

The Create card program allows you create a card program.

Endpoint

To create a card program, make a POST request to https://api.allawee.com/card-programs.

Response

The data in the payload of your request should include:

ATTRIBUTEDATA TYPE
DESCRIPTION
namestring
Your customer’s name.
descriptionstring
The description of the card program.
quantitynumber
The quantity of cards for the card program
distribution[object]
How cards created in this card program are delivered
- typestring
  bulked
- shippingAddress[object]
  object
  citystring
  City/District/Suburb/Town/Village.
  statestring
  State/County/Province/Region.
  countryCodestring
  Shipping address country
  phoneNumbernumber
  The cell number to be reached on while on delivery
  addressLineOnestring
  Street address/PO Box/Company name).
  addressLineTwostring
  (Apartment/Suite/Unit/Building).
- returnAddress[object]
  The return address when delivery was not possible
  citystring
  City/District/Suburb/Town/Village.
  statestring
  State/County/Province/Region.
  countryCodestring
  Shipping address country
  phoneNumberstring
  The contact person cell number
  addressLineOnestring
  Street (address/PO Box/Company name).
  addressLineTwostring
  (Apartment/Suite/Unit/Building).
personalization[object]
Custom design/artwork for cards in this card program
- frontArtworkFilestring
  public link to the design file for the front of the cards
- printCardholderNameboolean
  true
- defaultCardholderNamestring
  Default name to be printed on the card if not provided at point of creation
authorization[object]
Authorized accounts and webhooks to service cards in the program
- settlementAccountobject
  The account to be charged
- feesAccountobject
  A type of account for fees
- fundingSourceTypestring
  How the card should be funded
- webhookstring
  webhook created to be notified about events
- timeoutDefaultstring
  Action that should occur when there is a when transaction is timed-out
networkstring
The card network

Create a card program

This section assumes that you have gotten your authentication token. Use your token to make a POST request to the Create a card program like so:

If your request is successful, you will get a response with a 200 status code and a data field with information on your card program. Your response should look something like this.

Any other status code besides 200 is an error response. You can check our error responses to determine how you want to handle errors.

Example Customer Request

curl --request POST \
  --url https://api.allawee.com/card-programs \
  --header 'Authorization: Bearer token' \
  --data '{
    "name": "Card program",
    "quantity": 1,
    "currency": "NGN",
    "distribution": {
        "type": "bulked",
        "shippingAddress": {
            "city": "yaba",
            "state": "NG-LA",
            "countryCode": "NG",
            "phoneNumber": "+2349134902345",
            "addressLineOne": "100 Herbert macaulay way",
            "addressLineTwo": ""
        }
    },
    "personalization": {
        "frontArtworkFile": "https://figma.com",
        "defaultCardholderName": "Ciroma"
    },
    "authorization": {
        "settlementAccount": "ac.2tVZczWw7m6Teoeb7",
        "feesAccount": "ac.2tVZczWw7m6Teoeb7",
        "fundingSourceType": "settlement-account",
        "webhook": "wh.2tXPfsNc6CoZjbRWi",
        "timeoutDefault": "decline"
    },
    "network": "verve"
 }'

Example Cards Response

{
  "code": "success",
  "data": {
    "name": "Card program",
    "network": "verve",
    "quantity": 1,
    "currency": "NGN",
    "personalization": {
      "frontArtworkFile": "https://figma.com",
      "printCardholderName": false,
      "defaultCardholderName": "Ciroma"
    },
    "distribution": {
      "type": "bulked",
      "shippingAddress": {
        "city": "yaba",
        "state": "NG-LA",
        "countryCode": "NG",
        "phoneNumber": "+2349134902345",
        "addressLineOne": "100 Herbert macaulay way",
        "addressLineTwo": ""
      }
    },
    "authorization": {
      "fundingSourceType": "settlement-account",
      "webhook": "wh.2tXPfsNc6CoZjbRWi",
      "settlementAccount": "acct.2tVZczWw7m6Teoeb7",
      "feesAccount": "acct.2tVZczWw7m6Teoeb7",
      "timeoutDefault": "decline"
    },
    "status": "new",
    "createdAt": "2023-03-17T00:39:22.589Z",
    "updatedAt": "2023-03-17T00:39:22.589Z",
    "id": "c.prg.2tY3gamDwgZfxnKHS",
    "object": "card.program"
  }
}

Create a Card Program(Virtual Card)

The Create card program allows you create a virtual card program.

Endpoint

To create a virtual card program, make a POST request to https://api.allawee.com/card-programs.

Response

The data in the payload of your request should include:

ATTRIBUTEDATA TYPE
DESCRIPTION
namestring
Name of the card program
currencystring
The currency for the card program
personalization[object]
Custom name for cards in this card program
- defaultCardholderNamestring
  Default name to be printed on the card if not provided at point of creation
authorization[object]
Authorized accounts to service cards in the program
- fundingSourceTypestring
  How the card should be funded
networkstring
The card network

Create a card program

This section assumes that you have gotten your authentication token. Use your token to make a POST request to the Create a card program like so:

If your request is successful, you will get a response with a 200 status code and a data field with information on your card program. Your response should look something like this.

Any other status code besides 200 is an error response. You can check our error responses to determine how you want to handle errors.

Example Customer Request

curl --request POST \
  --url https://api.allawee.com/card-programs \
  --header 'Authorization: Bearer token' \
  --data '{
    "name": "Card program",
    "currency": "USD",
    "personalization": {
        "defaultCardholderName": "Allawee customer"
    },
    "authorization": {
        "fundingSourceType": "card-account"
    },
    "network": "mastercard"
 }'

Example Cards Response

{
  "code": "success",
  "data": {
    "name": "Card program",
    "network": "mastercard",
    "currency": "USD",
    "personalization": {
      "defaultCardholderName": "Allawee customer"
    },
    "authorization": {
      "fundingSourceType": "card-account"
    },
    "status": "live",
    "createdAt": "2023-03-17T00:39:22.589Z",
    "updatedAt": "2023-03-17T00:39:22.589Z",
    "id": "c.prg.2tY3gamDwgZfxnKHS",
    "object": "card.program"
  }
}

Request Approvals

The Request approvals API

Get Card Programs

Getting all card programs will show you all card programs created under your account.


GET	/card-programs

ATTRIBUTE
DATA TYPE
DESCRIPTION
limit
number
The number of card programs to fetch
sort
string
sort by state
before
string
you can use “before” as a cursor, which is the object ID that indicates the end of the previous page, enabling you to fetch the preceding page of the list by specifying it in your next call.
after
string
in order to navigate through a list of objects using pagination, you can use “after” as a cursor, which is the object ID indicating the start of the next page, and by including it in your next call, you can fetch the next page of the list.

Example Request

curl --location --request GET 'https://api.allawee.com/card-programs' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success",
  "message": "Request Successful",
  "data": [
    {
      "name": "Wema",
      "network": "verve",
      "quantity": 3,
      "currency": "NGN",
      "personalization": {
        "frontArtworkFile": "https://figma.com",
        "printCardholderName": false,
        "defaultCardholderName": "wema holders"
      },
      "distribution": {
        "type": "bulked",
        "shippingAddress": {
          "city": "ikeja",
          "state": "NG-LA",
          "countryCode": "NG",
          "phoneNumber": "+2348134543216",
          "addressLineOne": "42 yaba road lagos",
          "addressLineTwo": null
        }
      },
      "authorization": {
        "fundingSourceType": "settlement-account",
        "webhook": "wh.2tQRManbTRYSJdmYG",
        "settlementAccount": "acct.2tQAaDfgecFodwfgRR",
        "feesAccount": "acct.2tQAadHqaDoirdfgRR",
        "timeoutDefault": "decline"
      },
      "status": "live",
      "createdAt": "2023-02-22T12:49:18.204Z",
      "updatedAt": "2023-02-22T12:51:04.878Z",
      "id": "c.prg.2tQhBbJUiDt5ufA8e"
    },
    {
      "name": "Balenciaga cards",
      "network": "verve",
      "quantity": 3,
      "currency": "NGN",
      "personalization": {
        "frontArtworkFile": "https://figmafile.com",
        "printCardholderName": false,
        "defaultCardholderName": "Pocket Customer"
      },
      "distribution": {
        "type": "bulked",
        "shippingAddress": {
          "city": "Lekki",
          "state": "Lagos",
          "countryCode": "NG",
          "phoneNumber": "+2347080628645",
          "addressLineOne": "20 Adelowo Adedeji Street",
          "addressLineTwo": "Lekki Phase 1"
        }
      },
      "authorization": {
        "fundingSource": "settlement-account",
        "webhook": "wh.2tNF4hteZhrJFGfvj",
        "settlementAccount": "acct.2tNBQZcexMwRtgf3Ft",
        "feesAccount": "acct.2tNBQZcexEioeF7Ft",
        "fundingSourceType": "settlement-account",
        "timeoutDefault": "decline"
      },
      "lifeCycle": {
        "expirationOffset": "3y"
      },
      "controls": {
        "allowedCategories": ["flight-ticket"],
        "blockedCategories": ["betting"],
        "allowedChannels": ["atm", "pos"],
        "blockedChannels": ["online"],
        "spendingLimits": [
          {
            "amount": 1000,
            "interval": "monthly"
          }
        ]
      },
      "status": "new",
      "id": "c.prg.2tNFKg7aTD9qNix63u"
    }
  ],
  "metadata": {
    "hasMore": false
  }
}

Update Card Programs

The update card endpoint will update a particular card using the id.


PUT	/card-programs/{id}

idstring
The unique identifier of the card program to update

Body params

namestring
Your customer’s name.
descriptionstring
The description of the card program.
quantitynumber
The quantity of cards from the card program
distribution[object]
How cards created in this card program are delivered
- typestring
  bulked
- shippingAddress[object]
  object
  citystring
  City/District/Suburb/Town/Village.
  statestring
  State/County/Province/Region.
  countryCodestring
  Shipping address country
  phoneNumbernumber
  The cell number to be reached on while on delivery
  addressLineOnestring
  Street address/PO Box/Company name).
  addressLineTwostring
  (Apartment/Suite/Unit/Building).
- returnAddress[object]
  The return address when delivery was not possible
  citystring
  City/District/Suburb/Town/Village.
  statestring
  State/County/Province/Region.
  countryCodestring
  Shipping address country
  phoneNumberstring
  The contact person cell number
  addressLineOnestring
  Street address/PO Box/Company name).
  addressLineTwostring
  (Apartment/Suite/Unit/Building).
personalization[object]
Custom design/artwork for cards in this card program
- frontArtworkFilestring
  public link to the design file for the front of the cards
- printCardholderNameboolean
  true
- defaultCardholderNamestring
  Default name to be printed on the card if not provided at point of creation
authorization[object]
Authorized accounts and webhooks to service cards in the program
- settlementAccountobject
  The account to be charged
- feesAccountobject
  A type of account for fees
- webhook[object]
  webhook created to be notified about events

Update a card program

This section assumes that you have gotten your authentication token. Use your token to make a PUT request to the Update a card program like so:

If your request is successful, you will get a response with a 200 status code and a data field with information on your card program. Your response should look something like this.

Any other status code besides 200 is an error response. You can check our error responses to determine how you want to handle errors.

Example Customer Request

curl --request PUT \
  --url https://api.allawee.com/card-programs/{id} \
  --header 'Authorization: Bearer token' \
  --data '{
    "name": "string",
    "description": "string",
    "network": "verve",
    "quantity": 0,
    "currency": "NGN",
    "distribution": {
        "type": "bulked",
        "shippingAddress": {
        "city": "Yaba",
        "state": "Lagos",
        "countryCode": "NG",
        "phoneNumber": "+2348123456789",
        "addressLineOne": "No 10, Adekunle Close",
        "addressLineTwo": "Off Ciroma Rd"
        },
        "returnAddress": {
        "city": "Yaba",
        "state": "Lagos",
        "countryCode": "NG",
        "phoneNumber": "+2348123456789",
        "addressLineOne": "No 10, Adekunle Close",
        "addressLineTwo": "Off Ciroma Rd"
        }
    },
    "personalization": {
        "frontArtworkFile": "string",
        "printCardholderName": true,
        "defaultCardholderName": "string"
    },
    "authorization": {
        "settlementAccount": {},
        "feesAccount": {},
        "webhook": {},
        "timeoutDefault": "decline"
    }
 }'

Example Cards Response

{
  "code": "success",
  "message": "Request Successful",
  "data": {
    "name": "string",
    "description": "string",
    "network": "verve",
    "quantity": 4,
    "currency": "NGN",
    "distribution": {
        "type": "bulked",
        "shippingAddress": {
        "city": "Yaba",
        "state": "Lagos",
        "countryCode": "NG",
        "phoneNumber": "+2348123456789",
        "addressLineOne": "No 10, Adekunle Close",
        "addressLineTwo": "Off Ciroma Rd"
        },
        "returnAddress": {
        "city": "Yaba",
        "state": "Lagos",
        "countryCode": "NG",
        "phoneNumber": "+2348123456789",
        "addressLineOne": "No 10, Adekunle Close",
        "addressLineTwo": "Off Ciroma Rd"
        }
    },
    "personalization": {
        "frontArtworkFile": "https://figma.com",
        "printCardholderName": true,
        "defaultCardholderName": "Ramp holders"
    },
    "authorization": {
        "settlementAccount": {
            "settlement account"
        },
        "feesAccount": {
            "fees account"
        },
        "webhook": {
            "card requests"
        },
        "timeoutDefault": "decline"
    }
}

Delete Card Programs

Deleting a card program deletes the card program and the details no longer exists.


DELETE	/card-programs/{id}

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
unique identifier of the card program.

Example Request

curl --request DELETE \
  --url https://api.allawee.com/card-programs/{id} \
  --header 'Authorization: Bearer token' \
  --data '{ }'

{
  "code": "SUCCESS",
  "message": "Request Successful"
}

Accounts

Every card has an account that stores its funds, and Naira accounts can get money from other banks through NIP.

Create Accounts

The Accounts API allows you to create a new account

Endpoint

To create an Account, make a POST request to https://api.allawee.com/accounts.

Response

The data in the payload of your request should include:

ATTRIBUTEDATA TYPE
DESCRIPTION
namestring
Name of the account
typestring
The type of account
currencynumber
The currency of the account
enableDepositstring
Enable deposits on the account
metaDatastring
meta data

Endpoint


POST	accounts

Create Account

curl --request POST \
  --url https://api.allawee.com/accounts \
  --header 'Authorization: Bearer token' \
  --data '{
  "name": "settlement account",
  "type": "main",
  "currency": "NGN",
  "enableDeposit": true
}'

Get All Accounts

Retrieves current accounts based on specified query parameters.

Query params

limitnumber
The number of accounts to fetch
sortstring
sort by state
beforestring
you can use “before” as a cursor, which is the object ID that indicates the end of the previous page, enabling you to fetch the preceding page of the list by specifying it in your next call.
afterstring
in order to navigate through a list of objects using pagination, you can use “after” as a cursor, which is the object ID indicating the start of the next page, and by including it in your next call, you can fetch the next page of the list.

Endpoint


GET	accounts

Example Request

curl --location --request GET 'https://api.allawee.com/accounts&limit=100' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success",
  "data": {}
}

Get Balance

The Get Balance History API allows you to Fetch the balance of the specified account..

idstring
unique identifier of the specified account.

Endpoint


GET	accounts/{id}y

Example Request

curl --location --request GET 'https://api.allawee.com/accounts/{id} \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
  "data": {}
}

Simulation

This Simulation endpoints allows you make various card requests such as Create Card Authorization, Go live, Authorization Request Check .

Endpoint


POST	simulation/card-programs/{id}/go-live

POST	simulation/cards/{id}/request-authorization/check

POST	simulation/cards/{id}/request-authorization/capture

POST	simulation/cards/{id}/request-authorization/reverse-capture

POST	simulation/cards/{id}/request-authorization/update-capture

Card Program (Go live)

Endpoint

To go live, make a POST request to https://api.allawee.com/simulation/card-programs/{id}/go-live.

Query params

ARGUMENTREQUIRED
DESCRIPTION
idrequired
The id of the card program to perform the action on.

Endpoint


POST	simulation/card-programs/{id}/go-live

Example Request

curl --location --request POST 'https://api.allawee.com/simulation/card-programs/{id}/go-live' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
}

Request Authorization Check

This Authorization request check API checks the request from the card and you can make decision based on the requests coming from the webhook.

Query params

ARGUMENTREQUIRED
DESCRIPTION
idrequired
The id of the card to perform the action on.
channelstring
This paramenter specifies the channel through which the authorization is being made.

Endpoint


POST	simulation/cards/{id}/request-authorization/check

Example Request

curl --location --request POST 'https://api.allawee.com/simulation/cards/{id}/request-authorization/check' \
    --header 'Authorization: Bearer token'
    --data '{
      "channel": "atm"
    }'

Example

{
  "code": "success"
}

Request Capture Authorization

This endpoint allows the merchant to request authorization for a captured transaction, which means the transaction is ready to be settled.

Endpoint

To call the API, make a POST request to https://api.allawee.com/simulation/cards/{id}/capture.

Query params

ARGUMENTREQUIRED
DESCRIPTION
idrequired
The id of the card to perform the action on.
amountnumber
This parameter specifies the amount of the captured transaction.
feesnumber
This parameter specifies any fees assosciated with the captured transaction.
updateAmountnumber
This parameter specifies any updated fees associated with the captured transaction. If the transaction amount has changed since the authorization was requested, the merchant can update the amount here.
updateFeesnumber
This parameter specifies any updated fees associated witht the captured transaction.
channelstring
This channel parameter specifies the channel through which the authorization request was made. The channel parameter can helps to understand the context of the authorization request and make more informed decisions about whether to approve or decline the captured transaction

Endpoint


POST	simulation/cards/{id}

Example Request

curl --location --request POST 'https://api.allawee.com/simulation/cards/{id}/capture' \
    --header 'Authorization: Bearer token'
    --data '{
      "amount": 0,
      "fees": 0,
      "updateAmount": 0,
      "updateFees": 0,
      "channel": "atm"
    }'

Example

{
  "code": "success"
}

Request Reverse Capture

This endpoint allows the merchant to request a reversal of a previously authorized transaction. This can be useful in cases where the transaction needs to be cancelled or refunded.

Endpoint

To call the API, make a POST request to https://api.allawee.com/simulation/cards/{id}/request-authorization/reverse-capture.

Query params

ARGUMENTREQUIRED
DESCRIPTION
idrequired
The id of the card to perform the action on.
amountnumber
This parameter specifies the amount of the captured transaction that the merchant wants to reverse. This indicates that the merchant wants to reverse the entire captured amount.
feesnumber
This parameter specifies any fees associated with the captured transaction that the merchant wants to reverse.
channelstring
This paramenter specifies the channel through which request was made.

Endpoint


POST	simulation/cards/{id}/request-authorization/reverse-capture

Example Request

curl --location --request POST 'https://api.allawee.com/simulation/cards/{id}/request-authorization/reverse-capture' \
    --header 'Authorization: Bearer token'
    --data '{
      "amount": 0,
      "fees": 0,
      "channel": "atm"
    }'

Example

{
  "code": "success"
}

Request Update Capture Authorization

This endpoint allows the merchant to request an updated capture for a previously authorized transaction. This can be useful in cases where the final amount of the transaction has changed, or additional items need to be added to the transaction.

Endpoint

To call the API, make a POST request to https://api.allawee.com/simulation/cards/{id}/update-capture.

Query params

ARGUMENTREQUIRED
DESCRIPTION
idrequired
The id of the card to perform the action on.
amountnumber
This parameter specifies the amount of the captured transaction.
feesnumber
This parameter specifies any fees assosciated with the captured transaction.
updateAmountnumber
This parameter specifies any updated fees associated with the captured transaction. If the transaction amount has changed since the authorization was requested, the merchant can update the amount here.
updateFeesnumber
This parameter specifies any updated fees associated witht the captured transaction.
channelstring
This channel parameter specifies the channel through which the authorization request was made. The channel parameter can helps to understand the context of the authorization request and make more informed decisions about whether to approve or decline the captured transaction

Endpoint


POST	simulation/cards/{id}/update-capture

Example Request

curl --location --request POST 'https://api.allawee.com/simulation/cards/{id}/update-capture' \
    --header 'Authorization: Bearer token'
    --data '{
      "amount": 0,
      "fees": 0,
      "updateAmount": 0,
      "updateFees": 0,
      "channel": "atm"
    }'

Example

{
  "code": "success"
}

Receive a bank transfer payment

This endpoint allows you test the bank transfer pay-in process using the specified account number as the destination for the funds.

To call the API, make a POST request to https://api.allawee.com/simulation/payments/pay-in.

Query params

ARGUMENT
REQUIRED
DESCRIPTION
method
string
This key is set to “bank-transfer”, which indicates that the pay-in is being made through a bank transfer.
accountNumber
number
This is the account number for the recipient of the bank transfer.

Endpoint


POST	simulation/payments/pay-in

Example Request

curl --location --request POST 'https://api.allawee.com/simulation/payments/pay-in' \
    --header 'Authorization: Bearer token'
    --data '{
      "method": "bank-transfer",
      "accountNumber": "9978799989"
    }'

Example

{
  "code": "success"
}

Events

Events keep you informed about significant happenings in your account.

Get Events

This event API retrieves the list of events .

Query params

limitnumber
The number of events to fetch
sortstring
sort by state
beforestring
you can use “before” as a cursor, which is the object ID that indicates the end of the previous page, enabling you to fetch the preceding page of the list by specifying it in your next call.
afterstring
in order to navigate through a list of objects using pagination, you can use “after” as a cursor, which is the object ID indicating the start of the next page, and by including it in your next call, you can fetch the next page of the list.

Get One Event

The Get Event API allows you to Fetch the details of the specific event.

idstring
unique identifier of the event.

Endpoint


GET	events/{id}

Example Request

curl --location --request GET 'https://api.allawee.com/events/{id} \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
  "data": {}
}

Retry Events

This event API retries an event.

Query params

idstring
Unique identifier of the event

Endpoint


POST	events/{id}/retry

Example Request

curl --location --request POST 'https://api.allawee.com/events/{id}/retry' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success",
  "data": {}
}

Get Card Transaction

This Get Card Transaction API retrieves all card transactions.

Query params

limitnumber
The number of card transactions to fetch
sortstring
sort by state
beforestring
you can use “before” as a cursor, which is the object ID that indicates the end of the previous page, enabling you to fetch the preceding page of the list by specifying it in your next call.
afterstring
in order to navigate through a list of objects using pagination, you can use “after” as a cursor, which is the object ID indicating the start of the next page, and by including it in your next call, you can fetch the next page of the list.

Endpoint


GET	card-transactions

Example Request

curl --location --request GET 'https://api.allawee.com/card-transactions' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
}

Get One Card Transaction

The Get One Transaction API allows you to Fetch the details of the specified card transaction.

idstring
unique identifier of the specified card transaction.

Endpoint


GET	card-transactions/{id}

Example Request

curl --location --request GET 'https://api.allawee.com/card-transactions/{id} \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
  "data": {}
}

Get Card Authorizations

This Get Card Authorizations API retrieves all authorizations made on cards.

Query params

limitnumber
The number of card authorizations to fetch
sortstring
sort by state
beforestring
you can use “before” as a cursor, which is the object ID that indicates the end of the previous page, enabling you to fetch the preceding page of the list by specifying it in your next call.
afterstring
in order to navigate through a list of objects using pagination, you can use “after” as a cursor, which is the object ID indicating the start of the next page, and by including it in your next call, you can fetch the next page of the list.

Endpoint


GET	card-authorizations

Example Request

curl --location --request GET 'https://api.allawee.com/card-authorizations' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
}

Get One Card Authorization

The Get One Transaction API allows you to Fetch the details of the specific card authorization.

idstring
unique identifier of the specified card authorization.

Endpoint


GET	card-authorizations/{id}

Example Request

curl --location --request GET 'https://api.allawee.com/card-authorizations/{id} \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success"
  "data": {}
}

Disputes

This Disputes endpoint allows you dispute a transaction. You can dispute a transaction that the cardholder finds unfamiliar, considers potentially fraudlent, or faces any other concerns about.

Create a dispute

This section assumes that you have gotten your authentication token. Use your token to make a POST request to the Create a dispute like so:

Endpoint

To create a dispute, make a POST request to https://api.allawee.com/disputes.

Body

The data in the payload of your request should include:

ATTRIBUTEDATA TYPE
DESCRIPTION
sourcestring
The transaction id
reasonstring
The reason for reporting the dispute
- possible enum valuesfraudlent
  The cardholder did not initiate this transaction
- possible enum valuesduplicate
  The cardholder was charged twice for a single transaction
- possible enum valuesvalue-not-received
  The cardholder was charged but didn’t receive value
- possible enum valuesgeneral
  Other types of disputes

If your request is successful, you will get a response with a 200 status code and a data field with information on your disputes. Your response should look something like this.

Any other status code besides 200 is an error response. You can check our error responses to determine how you want to handle errors.

Example Customer Request

curl --request POST \
  --url https://api.allawee.com/disputes \
  --header 'Authorization: Bearer token' \
  --data '{
    "source": "c.txn.2uFu5fyyt1n3i7AGq",
    "reason": "value-not-received"
 }'

Example Cards Response

{
  "code": "success",
  "data": {
    "amount": 50000,
    "currency": "NGN",
    "status": "new",
    "source": "c.txn.2uFu5fyyt1n3i7AGn",
    "timeline": [
      {
        "action": "created",
        "actorType": "user",
        "actor": "usr.2tp3fYnThBByRzGtz",
        "createdAt": "2023-08-01T01:43:03.426Z",
        "updatedAt": "2023-08-01T01:43:03.426Z"
      }
    ],
    "reason": "value-not-received",
    "createdAt": "2023-08-01T01:43:03.426Z",
    "updatedAt": "2023-08-01T01:43:03.426Z",
    "id": "d.2uJrECrNWYdy82i5K",
    "object": "dispute"
  }
}

Update a Dispute

The update card endpoint allows you to update the data of a particular card using the id.


PUT	/disputes/{id}

idstring
The unique identifier of the dispute

Body params

textstring
A text requesting for an update of the dispute reported or inputting adding information to the disputes

Example Request

curl --request PUT \
  --url https://api.allawee.com/disputes/{id} \
  --header 'Authorization: Bearer token' \
  --data '{
    "text": "What's the update on this dispute"
}'

Example

{
  "code": "success",
  "data": {
    "amount": 50000,
    "currency": "NGN",
    "status": "new",
    "source": "c.txn.2uFu5fyyt1n3i7AGn",
    "timeline": [
      {
        "action": "created",
        "actorType": "user",
        "actor": "usr.2tp3fYnThBByRzGtz",
        "createdAt": "2023-08-01T01:43:03.426Z",
        "updatedAt": "2023-08-01T01:43:03.426Z"
      },
      {
        "action": "updated",
        "actorType": "customer",
        "actor": "cus.2ttTWz65gbPHDjR2B",
        "text": "What's the update on this dispute?",
        "createdAt": "2023-08-01T02:57:37.596Z",
        "updatedAt": "2023-08-01T02:57:37.596Z"
      }
    ],
    "reason": "value-not-received",
    "createdAt": "2023-08-01T01:43:03.426Z",
    "updatedAt": "2023-08-01T02:57:37.596Z",
    "id": "d.2uJrECrNWYdy82i5K",
    "object": "dispute"
  }
}

Close a Dispute

Close disputes let’s you close a dispute.


POST	/disputes/{id}/close

ATTRIBUTEDATA TYPE
DESCRIPTION
textstring
Added information concerning the dispute

Example Request

curl --request POST \
  --url https://api.allawee.com/disputes/{id}/close \
  --header 'Authorization: Bearer token' \
  --data '{
    "text": "can we close it?"
  }'

Example

{
  "code": "success",
  "data": {
    "action": "closed",
    "actorType": "customer",
    "actor": "cus.2ttTWz65gbPHDjR2B",
    "text": "can we close it?",
    "createdAt": "2023-08-01T12:15:10.057Z",
    "updatedAt": "2023-08-01T12:15:10.057Z"
  }
}

Get All Disputes

Getting all disputes will show you all disputes under your account.


GET	/disputes

ATTRIBUTEDATA TYPE
DESCRIPTION
limitnumber
A limit on the number of card disputes to be returned.
sortstring
Sort by state
beforestring
you can use “before” as a cursor, which is the object ID that indicates the end of the previous page, enabling you to fetch the preceding page of the list by specifying it in your next call.
afterstring
in order to navigate through a list of objects using pagination, you can use “after” as a cursor, which is the object ID indicating the start of the next page, and by including it in your next call, you can fetch the next page of the list.

Get One Dispute

Get one dispute lets you retrieve details about a specific dispute.


GET	/disputes/{id}

ATTRIBUTEDATA TYPE
DESCRIPTION
idstring
Unique identifier of the dispute

Example Request

curl --location --request GET 'https://api.allawee.com/disputes/{id}' \
    --header 'Authorization: Bearer token'

Example

{
  "code": "success",
  "data": {
    "amount": 50000,
    "currency": "NGN",
    "status": "new",
    "source": "c.txn.2uFu5fyyt1n3i7AGn",
    "timeline": [
      {
        "action": "created",
        "actorType": "user",
        "actor": "usr.2tp3fYnThBByRzGtz",
        "createdAt": "2023-08-01T01:43:03.426Z",
        "updatedAt": "2023-08-01T01:43:03.426Z"
      },
      {
        "action": "updated",
        "actorType": "customer",
        "actor": "cus.2ttTWz65gbPHDjR2B",
        "text": "What's the update on this dispute?",
        "createdAt": "2023-08-01T02:57:37.596Z",
        "updatedAt": "2023-08-01T02:57:37.596Z"
      },
      {
        "action": "updated",
        "actorType": "customer",
        "actor": "cus.2ttTWz65gbPHDjR2B",
        "text": "can we close it?",
        "createdAt": "2023-08-01T03:04:26.083Z",
        "updatedAt": "2023-08-01T03:04:26.083Z"
      }
    ],
    "reason": "value-not-received",
    "createdAt": "2023-08-01T01:43:03.426Z",
    "updatedAt": "2023-08-01T03:04:26.083Z",
    "id": "d.2uJrECrNWYdy82i5K",
    "object": "dispute"
  }
}


Introduction	How to use the Allawee API.
Endpoints	Descriptions of available data and their endpoints.
Testing	How to test the API.
Errors	Potential errors and what they mean.


GET	cards
GET	cards/{id}
POST	cards/link
POST	cards/{id}/activate
PUT	cards/{id}
POST	cards/{id}/block
POST	cards/{id}/unblock
DELETE	cards/{id}
POST	cards/{id}/reset-pin