API kinda sounded scary, but actually playing with the Windcave REST API helped me get much more insight into what REST API's are, and I can now more or less comfortably use it. I don't claim to know much, but I think I have a much better understanding of them now.
In REST API, you have four things you can do. But focusing on two operations (creating an object in the database, and querying an object in the database) seems to be beneficial especially when you are starting off with REST API, because those are the most natural things you would want to try to do.
Windcave REST API deals with 6 types.
- Purchase
- Refund
- Auth
- Complete
- Validate
- Void
Transaction
Transaction is a single object that refers to only one of the types. If you want to create a transaction object for a purchase type, you do:
POST https://dev.windcave.com/api/v1/transactions
Body>raw (JSON)
{
"type": "purchase",
"amount": "1.00",
"currency": "NZD",
"card": {
"cardNumber": "4111111111111111",
"dateExpiryYear": "20",
"dateExpiryMonth": "12",
"cvc2": "123"
}
}
Above is the minimum required fields filled in. This returns:
{
"id": "0000005f01623edc",
"links": [
{
"href": "https://dev.windcave.com/api/v1/transactions/0000005f01623edc",
"rel": "self",
"method": "GET"
}
]
}
Where id refers to the transaction object. The link with rel: self also refers to the id, as you can see that the id and the ending id of href are exactly the same.
We can view the result of transaction through query. Take the id returned, and do:
GET https://dev.windcave.com/api/v1/transactions/0000005f01623edc
Noting that the id goes at the end of the link. This returns
{
"id": "0000005f01623edc",
"username": "HajinK",
"authorised": true,
"allowRetry": false,
"reCo": "00",
"responseText": "APPROVED (00)",
"authCode": "101159",
"acquirer": {
"name": "Undefined",
"mid": "1000000",
"tid": "10000001"
},
"type": "purchase",
"method": "card",
"localTimeZone": "AEST",
"dateTimeUtc": "2020-12-13T21:11:59Z",
"dateTimeLocal": "2020-12-14T08:11:59+11:00",
"settlementDate": "2020-12-14",
"amount": "1.00",
"balanceAmount": "0.00",
"currency": "NZD",
"currencyNumeric": 554,
"clientType": "internet",
"card": {
"cardNumber": "411111........11",
"dateExpiryMonth": "12",
"dateExpiryYear": "20",
"type": "visa"
},
"cvc2ResultCode": "S",
"storedCardIndicator": "single",
"avs": {
"postCode": "",
"streetAddress": "",
"avsAction": 0,
"avsActionName": "DontCheck",
"avsResultCode": "U",
"avsResultDescription": "U - address information not available, or AVS is unavailable"
},
"isSurcharge": false,
"liabilityIndicator": "standard",
"links": [
{
"href": "https://dev.windcave.com/api/v1/transactions/0000005f01623edc",
"rel": "self",
"method": "GET"
},
{
"href": "https://dev.windcave.com/api/v1/transactions",
"rel": "refund",
"method": "POST"
}
]
}
The only notable fields are Links:
"links": [
{
"href": "https://dev.windcave.com/api/v1/transactions/0000005f01623edc",
"rel": "self",
"method": "GET"
},
{
"href": "https://dev.windcave.com/api/v1/transactions",
"rel": "refund",
"method": "POST"
}
]
The one with rel:self just refers to the transaction object, and that you can query the transaction through GET href. The second link is saying that you can refund the transaction by doing POST request with the href. But of course, refund also has required fields. This is how you refund the transaction with the id above:
POST https://dev.windcave.com/api/v1/transactions
{
"type": "refund",
"amount": "0.50",
"currency": "NZD",
"transactionId": "0000005f01623edc"
}
And this returns the result (where the id refers to the transaction object for the refund):
{
"id": "0000005f01623ed9",
"links": [
{
"href": "https://dev.windcave.com/api/v1/transactions/0000005f01623ed9",
"rel": "self",
"method": "GET"
},
{
"href": "https://dev.windcave.com/api/v1/transactions/0000005f01623ed8",
"rel": "parent",
"method": "GET"
}
]
}
The first link refers to itself (that transaction object referring to the refund), and the second link refers to the transaction of type purchase that has been refunded. This transaction object for refund can be viewed by doing the same thing as querying transaction of purchase type.
Of course, the result of refund can be queried. It will return a very long list like it did for querying transaction, so I won’t include it here.
You might want to void a transaction. Voidable transactions are: auth, refund, purchase. This can be done by doing a POST request like this (here we are refunding the above refund request):
POST: https://dev.windcave.com/api/v1/transactions
{
"type": "void",
"transactionId": "0000005f01623ed9"
}
This returns a list of things, but perhaps the most important thing is to check “responseText” (where it says APPROVED (00)). The above request returns:
{
"id": "0000005f01623ed9",
…….
"links": [
{
"href": "https://dev.windcave.com/api/v1/transactions/0000005f01623ed9",
"rel": "self",
"method": "GET"
},
{
"href": "https://dev.windcave.com/api/v1/transactions/0000005f01623ed9",
"rel": "parent",
"method": "GET"
}
]
}
Which contains the exact same id that we had for the refund. When this object is queried,
- How do you check that a transaction has been voided? (and similarly, refunded?)
=> Query the voided/refunded object, and check the message (responseText: APPROVED (00))
- Difference between auth – complete and purchase?
=> Auth simply makes a request to the bank to reserve certain amount of money from the client’s money (so like fuel station where they pre-emptively reserves 200 dollars). Complete requires the transactionId of auth transaction, and you specify how much will actually get deducted from the client’s bank.
Auth:
POST https://dev.windcave.com/api/v1/transactions
{
"type": "auth",
"amount": "5.00",
"currency": "NZD",
"card":{
"cardNumber": "4111111111111111",
"dateExpiryMonth": "10",
"dateExpiryYear": "23"
}
}
Complete:
//Same post endpoint, request body is as follows
{
"type": "complete",
"amount": "3.00",
"transactionId": "0000005f01623eee"
}