Update a transaction via an event

Events determine how the funds of a transaction are handled by LoanPro and Secure Payments.

The previous authorization resulted in a “pending” transaction, awaiting a decision on how the funds will be ultimately handled by LoanPro and Secure Payments. This request updates a transaction and determines how the funds from a transaction are applied to the cardholder’s line of credit account.

Before diving into the details of the request, there are a few things to note.

Like the request to authorize a transaction, this request uses a special set of credentials:

  • x-user-id : the user ID associated with your Secure Payments account
  • x-signature : a generated signature that uses your account’s swipe processor token and a pre-request script to generate a HMAC-SHA-512 hash.
  • x-request-id : a randomly generated GUID that represents the request to create a swipe event.

The payload of this request requires a random, unique event ID. This ID is used as a value within the “event_id” payload parameter and is used to identify this specific update event.

All of the above information is handled by scripts we’ve included within this guide's complementary Postman collection. We’ve included a pre-request script to help you send this request within your own workspace. This requires no additional work on your end. However, here’s the script as a reference:

// Generate and set variables used in the headers and payload of the request:
let uuid = require('uuid');
pm.collectionVariables.set('event-id', uuid.v4());

const message = pm.request.body.raw.replace('{{swipe-id}}', pm.collectionVariables.get('swipe-id')).replace('{{event-id}}', pm.collectionVariables.get('event-id')).replace('{{card-uuid}}', pm.collectionVariables.get('card-uuid'));
var hashHmacSHA512 = CryptoJS.HmacSHA512(message, pm.collectionVariables.get('swp-secret')).toString();
pm.collectionVariables.set('signature', hashHmacSHA512);

With the pre-request script configured, the following request is sent to authorize a transaction. Note that the following variables from previous steps are used within the payload of this request:

  • {card-uuid} : the UUID of the card used to authorize the transaction
  • {swipe-id} : the ID of the authorization transaction that’s being updated
curl --request POST \
     --url https://swipes.loanpro.io/byoi/event \
     --header 'x-request-id: {x-request-id}' \
     --header 'x-signature: {x-signature}' \
     --header 'x-user-id: {x-user-id}' \
     --data '
{
  "event-id": "{event-id}",
  "swipe-id": "{swipe-id}",
  "card-uuid": "{card-uuid}",
  "amount": 24.97,
  "type": "clearing"
}
'

In this example, the transaction is being “cleared”, meaning that funds moved from a card issuer’s account to the merchant acquirer’s account. This is determined by the “type” field. There are several different types of events, and they each affect transactions in a different way.

A successful request will result in the following response structure:

{
  "amount": 24.97,
  "event-id": "1e9b7ff9-807d-4b10-9ce7-93c3ad0b2fec",
  "swipe-id": "48383e03-683e-448e-90ea-38df5ac5d0f6",
  "issuer-details": "{\"event-id\":\"1e9b7ff9-807d-4b10-9ce7-93c3ad0b2fec\",\"swipe-id\":\"48383e03-683e-448e-90ea-38df5ac5d0f6\",\"card-uuid\":\"54e7a88f-5c8b-464b-abc5-fe9f20d7a436\",\"type\":\"clearing\",\"amount\":24.97,\"notes\":\"This is an optional note.\",\"metadata\":\"Swipe event metadata\"}",
  "card-uuid": "54e7a88f-5c8b-464b-abc5-fe9f20d7a436",
  "type": "clearing",
  "created": "2023-09-08T21:55:06Z",
  "result": "Cleared Amount = 24.97",
  "notes": "",
  "metadata": ""
}

View the API Reference to learn more ↗