Charging Payment Agreements

A payment agreement can be charged when the client's billing schedule is reached by simply calling the charge API with the payment agreement token for the customer and an amount.

The charge will be processed against the payment instrument linked to the payment agreement.

📘
Billing Scheduler
Please note that the scheduling of the billing is not coordinated by Wpay and instead will need to be processed by you or another payments provider.

curl --location --request PUT 'https://pt-api.wpay.com.au/wow/v1/pay/instore/merchant/payments/agreements/:paymentToken'
--header 'Content-Type: application/json' \
--header 'X-Api-Key: {{yourApiKey}}' \
--data-raw '{
  "data": {
    "paymentToken": "ce3ec653-199b-48c2-####-############",
    "amount": 2.99,
    "clientReference": "UNIQUE_CLIENT_REFERENCE",
    "orderNumber": "UNIQUE_ORDER_NO",
     "transactionType": {
        "creditCard": "PURCHASE"
        },
    "customerRef": "UNIQUE_CUSTOMER_REFERENCE"
  },
  "meta": {
    "fraud": {
        "provider": "cybersource",
        "version": "CyberSourceTransaction_1.101",
        "format": "XML",
        "responseFormat": "XML",
        "message": "<?xml version=\"1.0\" encoding=\"Windows-1252\"?>\r\n<RequestMessage xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">\r\n  <merchantID>TEST_MERCHANT_ID</merchantID>\r\n  <merchantReferenceCode>1234-26IO8JUN</merchantReferenceCode>\r\n  <billTo>\r\n    <firstName>Jane</firstName>\r\n    <lastName>Doe</lastName>\r\n    <street1>407 ELIZABETH STREET</street1>\r\n    <city>SURRY HILLS</city>\r\n    <state>NSW</state>\r\n    <postalCode>2199</postalCode>\r\n    <country>AU</country>\r\n    <phoneNumber>0400000000</phoneNumber>\r\n    <email>[email protected]</email>\r\n    <ipAddress>202.39.111.236</ipAddress>\r\n    <dateOfBirth>1987-02-14</dateOfBirth>\r\n    <customerID>3732442</customerID>\r\n  </billTo>\r\n  <shipTo>\r\n    <firstName>Jane</firstName>\r\n    <lastName>Doe</lastName>\r\n    <phoneNumber>0400000000</phoneNumber>\r\n    <email>[email protected]</email>\r\n  </shipTo>\r\n  <item id=\"0\">\r\n    <unitPrice>7.59</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Mccain Protein Plus Frozen Meal Satay Chicken</productName>\r\n    <productSKU>483660</productSKU>\r\n  </item>\r\n  <item id=\"1\">\r\n    <unitPrice>2.00</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Habee Savers Needles Household Repair</productName>\r\n    <productSKU>159489</productSKU>\r\n  </item>\r\n  <item id=\"2\">\r\n    <unitPrice>6.60</unitPrice>\r\n    <quantity>5</quantity>\r\n    <productName>Chicken Breast Fillet Skinless Small</productName>\r\n    <productSKU>118963</productSKU>\r\n  </item>\r\n  <item id=\"3\">\r\n    <unitPrice>5.43</unitPrice>\r\n    <quantity>5</quantity>\r\n    <productName>Chicken Drumsticks </productName>\r\n    <productSKU>169014</productSKU>\r\n  </item>\r\n  <item id=\"4\">\r\n    <unitPrice>3.50</unitPrice>\r\n    <quantity>4</quantity>\r\n    <productName>Chicken Thigh Cutlets Skinless</productName>\r\n    <productSKU>166830</productSKU>\r\n  </item>\r\n  <item id=\"5\">\r\n    <unitPrice>10.80</unitPrice>\r\n    <quantity>4</quantity>\r\n    <productName>Lamb Diced Heart Smart</productName>\r\n    <productSKU>208970</productSKU>\r\n  </item>\r\n  <item id=\"6\">\r\n    <unitPrice>4.94</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Macro Chicken Lovely Legs Free Range</productName>\r\n    <productSKU>700257</productSKU>\r\n  </item>\r\n  <item id=\"7\">\r\n    <unitPrice>19.64</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Macro Organic Whole Chicken</productName>\r\n    <productSKU>229320</productSKU>\r\n  </item>\r\n  <item id=\"8\">\r\n    <unitPrice>9.60</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Msa Australian Beef Steak Porterhouse</productName>\r\n    <productSKU>208988</productSKU>\r\n  </item>\r\n  <item id=\"9\">\r\n    <unitPrice>15.20</unitPrice>\r\n    <quantity>3</quantity>\r\n    <productName>Roast Pork Shoulder Boneless Small</productName>\r\n    <productSKU>203420</productSKU>\r\n  </item>\r\n  <item id=\"10\">\r\n    <unitPrice>10.80</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Select Corned Beef Silverside </productName>\r\n    <productSKU>148345</productSKU>\r\n  </item>\r\n  <item id=\"11\">\r\n    <unitPrice>13.00</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Clairol Nice N Easy 114a Natural Lightest Golden Brown</productName>\r\n    <productSKU>226536</productSKU>\r\n  </item>\r\n  <purchaseTotals>\r\n    <currency>AUD</currency>\r\n    <grandTotalAmount>298.09</grandTotalAmount>\r\n  </purchaseTotals>\r\n  <merchantDefinedData>\r\n    <mddField id=\"19\">Pickup</mddField>\r\n    <mddField id=\"10\">NO</mddField>\r\n    <mddField id=\"3\">Woolworths WOLLI CREEK, WOLLI CREEK</mddField>\r\n    <mddField id=\"1\">2017-09-22 16:00</mddField>\r\n    <mddField id=\"2\">NSW</mddField>\r\n    <mddField id=\"12\">NO</mddField>\r\n    <mddField id=\"16\">103</mddField>\r\n    <mddField id=\"23\"></mddField>\r\n    <mddField id=\"17\">2017-09-18 12:40</mddField>\r\n    <mddField id=\"18\">2017-09-18 12:40</mddField>\r\n    <mddField id=\"25\">2017-09-22 16:00</mddField>\r\n    <mddField id=\"20\">WEB</mddField>\r\n    <mddField id=\"57\">Normal</mddField>\r\n    <mddField id=\"58\"></mddField>\r\n    <mddField id=\"59\" />\r\n    <mddField id=\"60\">298.09</mddField>\r\n  </merchantDefinedData>\r\n  <afsService run=\"true\" />\r\n  <deviceFingerprintID>18S###-26IO####</deviceFingerprintID>\r\n</RequestMessage>"
    }    
  }
}'

var myHeaders = new Headers();
var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY";
var paymentToken = "PAYMENT_TOKEN";
myHeaders.append("Content-Type", "application/json");
myHeaders.append("X-Api-Key", yourAPIkey);

var raw = JSON.stringify({
  "data": {
    "paymentToken": paymentToken,
    "amount": 2.99,
    "clientReference": "UNIQUE_CLIENT_REFERENCE",
    "orderNumber": "UNIQUE_ORDER_NO",
    "transactionType": {
        "creditCard": "PURCHASE"
    	},
    "customerRef": "UNIQUE_CUSTOMER_REFERENCE"
  },
  "meta": {
    "fraud": {
        "provider": "cybersource",
        "version": "CyberSourceTransaction_1.101",
        "format": "XML",
        "responseFormat": "XML",
        "message": "<?xml version=\"1.0\" encoding=\"Windows-1252\"?>\r\n<RequestMessage xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">\r\n  <merchantID>TEST_MERCHANT_ID</merchantID>\r\n  <merchantReferenceCode>1234-26IO8JUN</merchantReferenceCode>\r\n  <billTo>\r\n    <firstName>Jane</firstName>\r\n    <lastName>Doe</lastName>\r\n    <street1>407 ELIZABETH STREET</street1>\r\n    <city>SURRY HILLS</city>\r\n    <state>NSW</state>\r\n    <postalCode>2199</postalCode>\r\n    <country>AU</country>\r\n    <phoneNumber>0400000000</phoneNumber>\r\n    <email>[email protected]</email>\r\n    <ipAddress>202.39.111.236</ipAddress>\r\n    <dateOfBirth>1987-02-14</dateOfBirth>\r\n    <customerID>3732442</customerID>\r\n  </billTo>\r\n  <shipTo>\r\n    <firstName>Jane</firstName>\r\n    <lastName>Doe</lastName>\r\n    <phoneNumber>0400000000</phoneNumber>\r\n    <email>[email protected]</email>\r\n  </shipTo>\r\n  <item id=\"0\">\r\n    <unitPrice>7.59</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Mccain Protein Plus Frozen Meal Satay Chicken</productName>\r\n    <productSKU>483660</productSKU>\r\n  </item>\r\n  <item id=\"1\">\r\n    <unitPrice>2.00</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Habee Savers Needles Household Repair</productName>\r\n    <productSKU>159489</productSKU>\r\n  </item>\r\n  <item id=\"2\">\r\n    <unitPrice>6.60</unitPrice>\r\n    <quantity>5</quantity>\r\n    <productName>Chicken Breast Fillet Skinless Small</productName>\r\n    <productSKU>118963</productSKU>\r\n  </item>\r\n  <item id=\"3\">\r\n    <unitPrice>5.43</unitPrice>\r\n    <quantity>5</quantity>\r\n    <productName>Chicken Drumsticks </productName>\r\n    <productSKU>169014</productSKU>\r\n  </item>\r\n  <item id=\"4\">\r\n    <unitPrice>3.50</unitPrice>\r\n    <quantity>4</quantity>\r\n    <productName>Chicken Thigh Cutlets Skinless</productName>\r\n    <productSKU>166830</productSKU>\r\n  </item>\r\n  <item id=\"5\">\r\n    <unitPrice>10.80</unitPrice>\r\n    <quantity>4</quantity>\r\n    <productName>Lamb Diced Heart Smart</productName>\r\n    <productSKU>208970</productSKU>\r\n  </item>\r\n  <item id=\"6\">\r\n    <unitPrice>4.94</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Macro Chicken Lovely Legs Free Range</productName>\r\n    <productSKU>700257</productSKU>\r\n  </item>\r\n  <item id=\"7\">\r\n    <unitPrice>19.64</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Macro Organic Whole Chicken</productName>\r\n    <productSKU>229320</productSKU>\r\n  </item>\r\n  <item id=\"8\">\r\n    <unitPrice>9.60</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Msa Australian Beef Steak Porterhouse</productName>\r\n    <productSKU>208988</productSKU>\r\n  </item>\r\n  <item id=\"9\">\r\n    <unitPrice>15.20</unitPrice>\r\n    <quantity>3</quantity>\r\n    <productName>Roast Pork Shoulder Boneless Small</productName>\r\n    <productSKU>203420</productSKU>\r\n  </item>\r\n  <item id=\"10\">\r\n    <unitPrice>10.80</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Select Corned Beef Silverside </productName>\r\n    <productSKU>148345</productSKU>\r\n  </item>\r\n  <item id=\"11\">\r\n    <unitPrice>13.00</unitPrice>\r\n    <quantity>2</quantity>\r\n    <productName>Clairol Nice N Easy 114a Natural Lightest Golden Brown</productName>\r\n    <productSKU>226536</productSKU>\r\n  </item>\r\n  <purchaseTotals>\r\n    <currency>AUD</currency>\r\n    <grandTotalAmount>298.09</grandTotalAmount>\r\n  </purchaseTotals>\r\n  <merchantDefinedData>\r\n    <mddField id=\"19\">Pickup</mddField>\r\n    <mddField id=\"10\">NO</mddField>\r\n    <mddField id=\"3\">Woolworths WOLLI CREEK, WOLLI CREEK</mddField>\r\n    <mddField id=\"1\">2017-09-22 16:00</mddField>\r\n    <mddField id=\"2\">NSW</mddField>\r\n    <mddField id=\"12\">NO</mddField>\r\n    <mddField id=\"16\">103</mddField>\r\n    <mddField id=\"23\"></mddField>\r\n    <mddField id=\"17\">2017-09-18 12:40</mddField>\r\n    <mddField id=\"18\">2017-09-18 12:40</mddField>\r\n    <mddField id=\"25\">2017-09-22 16:00</mddField>\r\n    <mddField id=\"20\">WEB</mddField>\r\n    <mddField id=\"57\">Normal</mddField>\r\n    <mddField id=\"58\"></mddField>\r\n    <mddField id=\"59\" />\r\n    <mddField id=\"60\">298.09</mddField>\r\n  </merchantDefinedData>\r\n  <afsService run=\"true\" />\r\n  <deviceFingerprintID>18S###-26IO####</deviceFingerprintID>\r\n</RequestMessage>"
    }    
  }
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch(`https://${environment}.wpay.com.au/wow/v1/pay/instore/merchant/payments/agreements/${paymentToken}`, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Where:

paymentToken is the payment agreement token generated when the payment agreement is created.
amount is the amount you wish to charge the specified payment agreement for.
clientReference is your application-specific reference number. This number should uniquely identify the transaction in your system
orderNumber is your order number of the transaction as generated during the order creation.
transactionType is the method by which you want to process the transaction, either as a preauth or as a purchase.
fraud is the CyberSource fraud payload for the transaction

🚧
Restricted API's
The Payment Agreement API's are IP restricted and do not allow unauthenticated server side calls. Your servers will need to be whitelisted to allow charges to be processed.

Charge Outcome

Following the charge, an outcome of the transaction is returned with the status of the payment agreement charge as well as the transaction references.

{
    "data": {
        "transactionId": "0349cfd3-3daa-4981-965f-cfea9ef749ec",
        "merchantReferenceId": "40252433",
        "merchantId": "10001",
        "paymentRequestId": "e7bacfb6-a59c-4578-89b0-6d7a56c37f5f",
        "grossAmount": 6.99,
        "clientReference": "36952873",
        "executionTime": "2021-12-20T06:34:57.068Z",
        "type": "PAYMENT",
        "status": "APPROVED",
        "instruments": [
            {
                "paymentInstrumentId": "1966757",
                "instrumentType": "CREDIT_CARD",
                "transactions": [
                    {
                        "type": "PAYMENT",
                        "executionTime": "2021-12-20T06:34:57.068Z",
                        "amount": 6.99,
                        "paymentTransactionRef": "1000000022049853",
                        "status": "APPROVED"
                    }
                ]
            }
        ],
        "subTransactions": [
            {
                "transactionReceipt": "1000000022049853",
                "paymentToken": "b5c65f37-a78c-45b5-b4e9-b77cdd3716e0",
                "paymentAgreement": {
                    "type": "RECURRING",
                    "paymentInstrumentId": "1966757",
                    "paymentInstrumentType": "CREDIT_CARD",
                    "startDate": "2021-12-20T17:34:51.227+11:00",
                    "endDate": "2023-12-31T23:59:59.999+11:00",
                    "chargeFrequency": "MONTHLY",
                    "chargeAmount": 6.99,
                    "expiryMonth": "11",
                    "cardSuffix": "1111",
                    "expiryYear": "22",
                    "scheme": "VISA"
                },
                "fraudResponse": {
                    "clientId": "6399820980916196203010",
                    "reasonCode": "100",
                    "decision": "ACCEPT"
                },
                "extendedTransactionData": [
                    {
                        "field": "bin",
                        "value": "444433"
                    },
                    {
                        "field": "stan",
                        "value": "651553"
                    },
                    {
                        "field": "rrn",
                        "value": "000000651553"
                    },
                    {
                        "field": "mid",
                        "value": "611000602008843"
                    },
                    {
                        "field": "terminalId",
                        "value": "W8843100"
                    }
                ],
                "externalServiceCode": "00",
                "externalServiceMessage": "APPROVED"
            }
        ]
    },
    "meta": {}
}

Transaction Outcomes

The status of your payment request is provided in the response as an externalServiceMessage. The outcome of a payment agreement charge can either be APPROVED or REJECTED.

Transaction Reference

The transaction ID transactionId is returned as part of a charge payment agreement response and is a unique reference to the charge request. A payment can be made up of multiple sub-transactions each with a paymentTransactionRef which is the unique reference of the sub-transaction.

The transactionId and paymentTransactionRef are important as these will be a required piece of information when either completing a pre-authorised transaction, voiding the transaction or processing a refund.

Fraud Outcomes

Should you use the fraud services of Wpay the fraud outcome (fraudResponse) in the payment response will give you the outcome of the fraud decision manager check. This can be Accept, Reject or Review.

Accept: No fraud detected. Advice is that payment can proceed.
Reject: Fraud likely. Advice is that payment should be voided or refunded.
Review: Fraud potential. Payment should be manually reviewed to determine fraud decision.

Charging Payment Agreements

📘
Billing Scheduler

🚧
Restricted API's

Charge Outcome

Transaction Outcomes

Transaction Reference

Fraud Outcomes

📘Billing Scheduler

🚧Restricted API's

Charge Outcome

Transaction Outcomes

Transaction Reference

Fraud Outcomes

📘
Billing Scheduler

🚧
Restricted API's