Refund transaction

Request

For below {code} needs to be replaced with your transaction's code.

Live

POST https://fumopay.app/transaction/refund/{code}

Test

POST https://fumopay.dev/transaction/refund/{code}

Payload

{
    "profile_key": "your public key",
    "amount": 100,
    "currency": "GBP",
    "transaction_id": "transaction code",
    "to_account": {
        "name": "name",
        "scheme": "Number scheme",
        "number": "number",
        "bank_id": 1,
    },
    "signature": "Signed fields",
    "signature_date": "Date signed"
}

Field descriptions

field	usage
profile_key	This is your public key from the profile that you are using
amount	The amount in minor units, eg. £1.34 is 134
currency	3 digit ISO currency code. This currently only accepts GBP
transaction_id	Transaction code
to_account	This is the account where the returns should be sent to. Retrieve this detail via the get endpoint
name	The customer's account name
scheme	UK.OBIE.SortCodeAccountNumber or UK.OBIE.IBAN. See number for more details
number	If scheme above is UK.OBIE.SortCodeAccountNumber then number follows the format {sort code}{account number} for a total of 6+8=14 numeric digits. If it is UK.OBIE.IBAN then this needs to contain the customer's IBAN
bank_id	The bank id for the customer's bank as retrieved from bank API. Please note that the bank must support refunds. This is checked via the existence of the receive_only field
signature	The signed request which is detailed below
signature_date	ISO 8601 / RFC 3339 date in the format YYYY-MM-DDTHH:MM:SSZ This date is valid for 5 minutes

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 + profile_key + currency + amount + signed_date + secret_key
hash = sha512(strToHash)
signature = base64.encode(hash)

The secret key is from the profile that you are using.

See code examples below.

Response

{
    "result": "1",
    "error": "error description",
    "url": "a fumopay url"
}

Field descriptions

field	usage
result	The result of the call. Please see status codes
error	The error message if not successful
url	The url to complete the refund.

Signing Code examples

JavaScript

const signDate = (new Date()).toISOString()
let toHash = `${transaction_id}${profile_key}${currency}${amount}${signDate}${secret_key}`
const msgUint8 = new TextEncoder().encode(toHash)
const hashBuffer = await crypto.subtle.digest("SHA-512", msgUint8)
let signature = window.btoa(String.fromCharCode(...new Uint8Array(hashBuffer)))

PHP

$signed = date('c')
$strToHash = implode('',[$transaction_id, $profile_key, $currency, $amount, $signed, $secret_key]);
$hashed = hash("sha512", $strToHash, true);
$signature = base64_encode($hashed);

Golang

signedDate = time.Now().UTC().Format(time.RFC3339)
stringToHash := fmt.Sprintf("%s%s%s%d%s%s", transaction_id, profile_key, currency, amount, signedDate, secretKey)
hash := sha512.New()
hash.Write([]byte(stringToHash))
signature := base64.StdEncoding.EncodeToString(hash.Sum(nil))

Python

signedDate = datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0).isoformat()
stringToHash = "".join([transaction_id, profile_key, currency, amount, signedDate, secretKey])
hash = hashlib.sha512(stringToHash.encode('utf-8'))
signature =  base64.b64encode(hash.digest()).decode("utf-8")

Dart

final signatureDate = DateTime.now().toUtc().toIso8601String();
final strtoHash = "$transaction_id$profile_key$currency$amount$signatureDate$secretKey";
var bytes = utf8.encode(strtoHash);
var digest = sha512.convert(bytes);
var signature = base64.encode(digest.bytes);