Web hook
The web hook posts the result of a transaction, refund, recurring payment to your server. Please review profile to configure your web hook URL. The JSON body looks like follows:
Transaction
POST your.site/web-hook-url
{
"transaction_id": "fumo transaction code",
"timestamp": "UTC request timestamp",
"reference": "Your internal reference",
"result": "1",
"result_text": "ok",
"type": "transaction",
"signature": "Signed fields"
}
Field descriptions
| field | usage |
|---|---|
| transaction_id | This is the fumo transaction code |
| timestamp | UTC Timestamp in the RFC 3339/ISO 8601 format 2024-03-15T08:15:27Z |
| reference | Your reference for the transaction |
| result | The result of the call. Please see status codes |
| result_text | The result of the call but as a string. Please see status codes |
| type | This will be transaction |
| signature | The signed request which is detailed below |
Request signing
The signature is the concatenation of certain fields which is then given a SHA512 hash which is finally base64 encoded. In pseudo code as follows:
strToHash = transaction_id + reference + result + profile_key + secret_key + timestamp
hash = sha512(strToHash)
signature = base64.encode(hash)
The profile and secret keys are from the profile that you are using.
Response
If your server responds to the above request with a HTTP status 200 or 201 we will see the transaction notification as completed. Any other status we will retry 5 times.
Refund
POST your.site/web-hook-url
{
"refund_id": "fumo refund code",
"timestamp": "UTC request timestamp",
"reference": "Your internal reference",
"result": "1",
"result_text": "ok",
"type": "refund",
"signature": "Signed fields"
}
Field descriptions
| field | usage |
|---|---|
| refund_id | This is the fumo refund code |
| timestamp | UTC Timestamp in the RFC 3339/ISO 8601 format 2024-03-15T08:15:27Z |
| reference | Your reference for the refund |
| result | The result of the call. Please see status codes |
| result_text | The result of the call but as a string. Please see status codes |
| type | This will be refund |
| signature | The signed request which is detailed below |
Request signing
The signature is the concatenation of certain fields which is then given a SHA512 hash which is finally base64 encoded. In pseudo code as follows:
strToHash = refund_id + reference + result + profile_key + secret_key + timestamp
hash = sha512(strToHash)
signature = base64.encode(hash)
The profile and secret keys are from the profile that you are using.
Response
If your server responds to the above request with a HTTP status 200 or 201 we will see the refund notification as completed. Any other status we will retry 5 times.
Recurring Payment
POST your.site/web-hook-url
{
"subscription_id": "fumo subscription code",
"transaction_id": "fumo transaction code",
"timestamp": "UTC request timestamp",
"reference": "Your internal reference",
"result": "1",
"result_text": "ok",
"type": "recurring",
"count": 3,
"payment": {
"id": "subscription payment code",
"amount": 100,
"number": 1,
},
"signature": "Signed fields"
}
Field descriptions
| field | usage |
|---|---|
| subscription_id | This is the fumo subscription code and should be used to track all subsequent payment notifications. |
| transaction_id | This is the fumo transaction code. This will match the code of the transaction when created and will always be present on the first notification. |
| timestamp | UTC Timestamp in the RFC 3339/ISO 8601 format 2024-03-15T08:15:27Z |
| reference | Your reference for the recurring payment |
| result | The result of the call. Please see status codes |
| result_text | The result of the call but as a string. Please see status codes |
| type | This will be recurring |
| count | If known the number of payments in the subscription |
| payment | If there is a payment associated with this notification this will be present |
| payment.id | The subscription payment code |
| payment.amount | The amount that was paid for this payment |
| payment.number | The index number of the payment. This starts from 1. |
| signature | The signed request which is detailed below |
Request signing
The signature is the concatenation of certain fields which is then given a SHA512 hash which is finally base64 encoded. In pseudo code as follows:
strToHash = subscription_id + reference + result + profile_key + secret_key + timestamp
hash = sha512(strToHash)
signature = base64.encode(hash)
The profile and secret keys are from the profile that you are using.
Response
If your server responds to the above request with a HTTP status 200 or 201 we will see the recurring payment notification as completed. Any other status we will retry 5 times.
Note on recurring payments
There are different methods for creating a recurring payment from our side. The main notification line is that when the instructions have been set up we will send a notification without a payment object with a 14 (scheduled) result. Then subsequent notifications should contain the individual payments with a result of 11 (paid).
In the case where we had to take the payment at the same time as the instruction set up we will respond with a 11 (paid) result and the payment object will be populated.