Payment Complete

1. Payment Complete Webhook Overview

The Payment Complete Webhook provides a method to get payment data into Payments2Us/Salesforce.  The payment details will be created in the Payment Txn Object and processed by our Batch Processor to perform the creation of Accounts/Contacts/Opportunity/Campaign members as per standard Payments2Us processing.

Setting up and using Webhooks will require advanced admin skills or developer skills.  For this reason, this guide is all that is available under standard support.  Should you require more information and/or assistance, one of our premium support packages is required.

If your organisation has elected to create their own payment/donation form that process credit cards and to send the results through to Payments2us via this webhook then please ensure the platform capturing the card and transferring the card information is PCI Compliant.  Please also make sure that your form has anti-spamming and CAPTCHA enabled.  

Your custom form and transacting is between your organisation and your developer.  That form is not covered by Payments2Us Support.  Once the information is in Salesforce, then our support can assist.

Shopping Cart transactions are shown in the webhook Payload.  These are planned for future updates and not currently available.

2. License Key

2.1. Obtaining a License Option Key

You can see the pricing for Webhook API at: https://www.payments2us.com/about/payments2us-pricing-plans/

To order a license key, please contact support @ payments2us.com

After your order has been processed, you will receive an email with the license key details. You need to update your Salesforce instance to have this key entered against all merchant facilities.

Details on where/how to enter the License Option Key are in the email that you'll receive.

3. Authentication

This service is a REST service and can be accessed using the oAuth flow or as a public URL using Force.com Sites.  

Both options need to have the header Payments2Us-Key set.

oAuth

  • We recommend the oAuth Option.
  • This involves creating a connected App and using the oAuth flow.
  • The User that Authenticates the App must have the Permission Set "Payment2Us API" assigned

Force.com Sites

  • This option is useful when using Webhooks through Zapier or similar integration products that do not have an oAuth option for webhooks.
  • The Force.com Sites User must have the Permission Set "Payment2Us API" assigned.

4. Webhook endpoint URL

The endpoint is:

https://{your salesforce instance}/services/apexrest/AAkPay/v1/wh/PaymentComplete/{payment form record id}

Where {payment form record id} is the salesforce record Id of the Payment Form record (1).

Where "your salseforce instance" can be either a my salesforce domain reference or a force.com site (Not recommended option (2) ).

 

5. Header Parameters

The following Header parameters are required

  • Content-Type : application/vnd.api+json
  • Payments2Us-Key : {Webhook Secret Key}

You can locate the Webhook Secret Key from the Payment Form "Webhook Secret Key".  If this field is blank, assign your own values.

6. Sample Request Body

Http Method: POST

{
  "Reference" : {
    "UniqueOrderNo" : "1002",
    "Status" : "Receipting Complete",
    "PaymentOptionId" :	"a022G00000MmTB6",
    "OpportunityId" : "0062G00000hYvSu",
    "CampaignId" : "701A0000000ZY7y",
    "PayerIPAddress" : "201.201.0.0"
  },
	"Contact": {
    "ContactId" : "0032G00002Kpoko",
    "Title" : "CEO",
    "Salutation" : "Mr",
    "FirstName" : "John",
    "LastName" : "Smith",
    "MailingStreet" : "100 Collins St",
    "MailingCity" : "Melbourne",
    "MailingState" : "VIC",
    "MailingPostalCode" : "3000",
    "MailingCountry" : "Australia",
    "OtherStreet" : "100 Collins St",
    "OtherCity" : "Melbourne",
    "OtherState" : "VIC",
    "OtherPostalCode" : "3000",
    "OtherCountry" : "Australia",	    
    "Phone" : "03 8080 9000",
    "MobilePhone" : "0419 99 9999",
    "Email" : "john.smith@mailinator.com",
    "MembershipId" : "100"
	},
	"Account" : {
	  "AccountId" : "001A000000q9rJt",
	  "PaymentBy" : "Company",
	  "PaymentByName" : "Smith Enterprises"
	},
	"TransactionDetail" : {
	  "Amount": 100.00,
	  "DonationAmount": 40.00,
	  "FreightAmount": 0.00,
	  "DiscountBasis": "Amount",
	  "DiscountValue": 10.00,
	  "TaxAmount": 9.09,
	  "CurrencyCode" : "AUD",
	  "TaxCalculation" : "Amounts Include Tax",
	  "PayFrequency" : "Monthly",
      "PaymentDay" : "1",
	  "PaymentFor" : "Widget and Donation",
	  "PaymentMethod"	: "Credit Card",
	  "TransactionDate" : "2021-05-23",
	  "BankDepositDate" : "2021-05-24"
	},
  "PaymentGatewayResponse": {
    "PaymentStatus": "1",
    "TxnRef" : "ch_1I4gUIGksEkehvPvt0hPl4hk",
    "PaymentResponseCode" : "",
    "PaymentResponseText" : "approved_by_network",
    "PaymentResponseDesc" : "Payment complete",
    "BillingToken" : "0000120002798754",
    "CustomerProfileId" : "cus_IfugQUWoWiKqy0",
    "CardType":"Visa",
    "MaskedCardNumber": "4557....1110",
    "CardExpiry" : {
      "CardExpiryMonth" : 12,
      "CardExpiryYear" : 2025
    }
  },	
	"CustomFields" : {
	  "CustomRefFieldName" : "Application__c",
	  "CustomRefFieldId" : "a0k2G00000PcvQN",
      "CustomField1Name" : "Colour__c",
      "CustomField1Value" : "Red",
      "CustomField2Name" : "",
      "CustomField2Value" : "",
      "CustomField3Name" : "",
      "CustomField3Value" : "",
      "CustomField4Name" : "",
      "CustomField4Value" : "",                  
	  "CustomFieldsNVP" : [{
	    "CustomFieldName" : "Colour__c",
	    "CustomFieldValue" : "Red"
	  } 
      ]
	},
	"ShoppingCartDetails" : {
	  "cartlines" : [{
	    "itemcode" : "SKU2006-001", 
	    "itemdesc":"my item notes for SKU",
	    "quantity" : 10.00, 
	    "unitprice" :100.00, 
	    "tax" : 10.00
	  }]
  }
}

7. Sample Response

{ "Success": false, "PaymentTxnId": null, "ErrorMsg": "Payment Txn is not at a status that can be updated" }

8. Element Descriptions


Element Description Salesforce Field
Reference
AAkPay__Payment_Txn__c (Object)
  • UniqueOrderNo
Used to locate existing Payment Txn where the record type is "Payment" and the AAkPay__Reference__c field matches this value.
If a Payment is located and has a status of Confirmation, Payment Complete or Receipting Complete then it will update updated, otherwise an error will be returned for any other status
AAkPay__Reference__c 
  • Status
Must be one of: Confirmation, Payment Complete or Receipting Complete.  If left blank then Payment Complete is used
AAkPay__Status__c
  • PaymentOptionId
Salesforce Record Id for the Payment Option used
AAkPay__payment_Option__c
  • OpportunityId
Salesforce Record Id for the Opportunity. If left blank, then if enabled, the normal Payments to us processing will be used to create an opportunity.
AAkPay__Opportunity__c
  • CampaignId
Salesforce Record Id for the Opportunity. 
AAkPay__Campaign__c
  • PayerIPAddress
The IP address of the payer/donor that made the donation
AAkPay__IP_Address__c
Contact
AAkPay__Payment_Txn__c (Object)
  • ContactId
Salesforce Record Id for the Contact.  If not specified, the Payments2Us Matching routines will be used to located or create a Contact
AAkPay__Contact__c
  • Title
Contacts Job Title
AAkPay__Title__c
  • Salutation
Contacts Salutation e.g. Mr, Mrs, Dr etc.
AAkPay__Salutation__c
  • FirstName
Contacts First Name
AAkPay__FirstName__c
  • LastName
Contacts Last Name
AAkPay__LastName__c
  • MailingStreet
Contacts Mailing Street
AAkPay__MailingStreet__c
  • MailingCity
Contacts Mailing City
AAkPay__MailingCity__c
  • MailingState
Contacts Mailing State.  If not specified, the default State from the Merchant Facility is used.
AAkPay__MailingState__c
  • MailingPostalCode
Contacts Mailing Postal Code
AAkPay__MailingPostalCode__c
  • MailingCountry
Contacts Mailing Country.  If not supplied, the default country on the Merchant Facility is used. AAkPay__MailingCountry__c
  • OtherStreet
Contacts Other Street 
AAkPay__OtherStreet__c
  • OtherCity
Contacts Other City
AAkPay__OtherCity__c
  • OtherState
Contacts Other State
AAkPay__OtherState__c
  • OtherPostalCode
Contacts Other Postal Code
AAkPay__OtherPostalCode__c
  • OtherCountry
Contacts Other Country
AAkPay__OtherCountry__c
  • Phone
Contacts Phone
AAkPay__Phone__c
  • MobilePhone
Contacts Mobile Phone
AAkPay__MobilePhone__c
  • Email
Contacts Email
AAkPay__Email__c
  • MembershipId
Membership No.  If not specified, one is populated automatically from the Membership Next No. auto number field on the Payment Txn.
AAkPay__Membership_Id__c
Account
AAkPay__Payment_Txn__c (Object)
  • AccountId
Salesforce Record Id for the Account.  If not specified, the Payments2Us Matching routines will be used to located or create a Account.
AAkPay__Account__c
  • PaymentBy
"Individual", "Company" etc.  Determines if this transaction is at the contact (Individual) level or at the organisation (Company) level.  This should match one of the options selected on the Payment Form (Payments2Us Tab) being used
AAkPay__Donation_By__c
  • PaymentByName
If "PaymentBy" is NOT individual then a value should be specified here as the transaction is for a Company/Organisation type transaction.
AAkPay__Donation_By_Name__c
TransactionDetail

AAkPay__Payment_Txn__c (Object)
  • Amount
Amount of the payment exclusive of taxes, freight, service fee, surcharges.  
AAkPay__Amount__c
  • DonationAmount
Amount of the donation.  This field will not incur taxes. 
AAkPay__Donation_Amount__c
  • FreightAmount
Freight Amount
AAkPay__Freight__c
  • DiscountBasis
Basis for a discount given.  Values are "Amount" or "Percent".  This value is used in conjunction with "DiscountValue" field.
AAkPay__Discount_Basis__c
  • DiscountValue
If the DiscountBasis is "Amount", then the value is assigned to the AAkPay__Discount_Amt__c field.  If the DiscountBasis is "Percent" then the value is assigned to  the AAkPay__Discount__c field.
AAkPay__Discount_Amt__c or AAkPay__Discount__c
  • TaxAmount
This value is only applicable when the Tax Calculation is "Tax Amount Specified Inclusive" or "Tax Amount Specified Exclusive".  If the Tax Calculation is not one of these, then the tax amount is automatically calculated.
AAkPay__Tax_Amount__c
  • CurrencyCode
3 Digit ISO Currency Code.  If not specified, the Default Currency on the Merchant Facility is assigned.
AAkPay__Currency__c
When multi currency is enabled, CurrencyIsoCode is updated.
  • TaxCalculation
Determines how Tax is calculated.
If blank, then the "Tax Calculation" on the Merchant Facility is used.
Valid "No Tax", "Amounts Include Tax", "Amounts Exclude Tax", "Tax Amount Specified Inclusive", "Tax Amount Specified Exclusive"

AAkPay__Tax_Calculation__c
  • PayFrequency
If left blank, "One-off" will be assigned.
If the value set here is NOT "One-off" AND a valid is in "BillingToken" then a Recurring Payment record will be created during the Matching process.

Valid values include: "One-off","One-off - Authorise","Daily","Weekly","Fortnightly","4 Weeks","Monthly","Bi-Monthly","Quarterly","Six Monthly","Annually","Two Yearly".
AAkPay__Regular_Pymt_Freq__c
  • PaymentMethod
Method of Payment.  Valid Values include "Credit Card", "Manual", "Direct Debit"
AAkPay__Method_of_Payment__c and AAkPay__Payment_Source__c
  • TransactionDate
Date of the transaction in YYYY-MM-DD format AAkPay__Transaction_Date__c
  • BankDepositDate
Date the payment is expected to be settled in the bank account in YYYY-MM-DD format AAkPay__Bank_Deposit_Date__c
PaymentGatewayResponse

AAkPay__Payment_Txn__c (Object)
  • PaymentStatus
This should be "1" if the payment was successful.  If left blank, this will be set to "1"
AAkPay__Payment_Status__c
  • TxnRef
The Payment Gateway Response transaction reference.  NOTE, this is required for refunds through Payments2Us.

For Windcave, "dpsTxnRef".
For Stripe, Charges or Payment Intention - "Id".
For EziDebit, "PaymentID" from "Payment Detail"
For NAB Transact, "txnID" from "PeriodicItem".
For DataTrans, "transactionId".
For Authorize.net, "transId".
AAkPay__dpsTxnRef__c
  • PaymentResponseCode
Payment Gateway Response code.
AAkPay__Payment_Response_Code__c
  • PaymentResponseText
Payment Gateway Response text.
AAkPay__Payment_Response_Text__c
  • PaymentResponseDesc
Payment Gateway Response description.
AAkPay__Payment_Response_Desc__c
  • BillingToken
The Payment Gateway Reference to the Token or Card Details on file.  This is required for Regular Payments/Donations.  It must be supplied if PayFrequency is NOT One-off.
AAkPay__DpsBillingId__c
  • CustomerProfileId
The Payment Gateway Reference to the Customer on file.  This is required for some payment gateways for Regular Payments/Donations.  If the Payment Gateway requires this, then it must be supplied if PayFrequency is NOT One-off.
.
For Stripe, Customer - "Id".
For EziDebit, "CustomerRef" from "New Customer"
For NAB Transact, Please assign unique reference of GUID.
For DataTrans, "transactionId".
For Authorize.net, "customerProfileId".
AAkPay__Payment_Gateway_Customer_ProfileId__c
  • CardType
Type of card - e.g Visa, Mastercard etc.
AAkPay__Payment_CC__c
  • MaskedCardNumber
Masked version of the Credit Card.  DO NOT send full card details through.
AAkPay__Payment_CC_No__c
  • CardExpiry


  •       CardExpiryMonth
2 Digit expiry month of the card.  Used for expiry reminders in regular giving.  For example "02" for February.
AAkPay__Payment_CC_Exp_Date_Month__c
  •       CardExpiryYear
4 Digit expiry month of the card.  Used for expiry reminders in regular giving. For example 2021.
AAkPay__Payment_CC_Exp_Date_Year__c
CustomFields

AAkPay__Payment_Txn__c (Object)
  • CustomRefFieldName
API field name for a lookup reference field on the Payment Txn Object.  Note, this cannot be a Payments2Us standard field/managed package field.
  • CustomRefFieldId
Used in conjunction with "CustomRefFieldName".  This is a 15 or 18 digit record Id for the lookup field/object.
  • CustomField1Name
API field name of a field on the Payment Txn Object.  Note, this cannot be a Payments2Us standard field/managed package field.
  • CustomField1Value
Used in conjunction with "CustomField1Name".  This is a value to populate in the field.
  • CustomField2Name
API field name of a field on the Payment Txn Object.  Note, this cannot be a Payments2Us standard field/managed package field.
  • CustomField2Value
Used in conjunction with "CustomField2Name". This is a value to populate in the field.
  • CustomField3Name
API field name of a field on the Payment Txn Object.  Note, this cannot be a Payments2Us standard field/managed package field.
  • CustomField3Value
Used in conjunction with "CustomField3Name". This is a value to populate in the field.
  • CustomField4Name
API field name of a field on the Payment Txn Object.  Note, this cannot be a Payments2Us standard field/managed package field.
  • CustomField4Value
Used in conjunction with "CustomField4Name". This is a value to populate in the field.
  • CustomFieldsNVP
This array is an alternative method to the Custom Fields [1..4] Name/Value that can be entered above.  
This element note allows for upto 10 name/value pairs.

  •       CustomFieldName
API field name of a field on the Payment Txn Object.  Note, this cannot be a Payments2Us standard field/managed package field.
  •       CustomFieldValue
Used in conjunction with "CustomFieldName".  This is a value to populate in the field.
ShoppingCartDetails These details are similar to Shopping Cart Details URL Parameter. AAkPay__Payment_Item__c (Object)
  • cartlines
Array of shopping cart line items
  •           itemcode
Product Item Code
AAkPay__Product_Id__c and AAkPay__SKU__c
  •           itemdesc
Product Description
AAkPay__Item_Description__c
  •           quantity
Quantity in cart
AAkPay__Quantity__c
  •           unitprice
Unit price of product
AAkPay__Price__c
  •          disc
Discount amount given
AAkPay__Discount__c
  •           tax
Tax amount charged AAkPay__Tax_Amount__c

9. Example with Zapier

The below is an example using Zapier Webhook POST.

  1. Webhook endpoint URL
  2. Select "Json" Payload Type
  3. Payload Elements.  Note the double underscore.  All fields in the Reference Element start with "Reference__".
  4. Header Parameters