The design of web payments integration assumes the customer is making a Beacon call prior to the integration that contains the set up IDs to begin the payment process. Typically that ID will be a contact ID or an invoice ID. 


EXAMPLE 1: Collecting Payment from the Client on the Invoice

To execute this scenario, you need three things:

  • an invoice ID

  • an encrypted and time limited token that is generated by PEAK 15

  • the merchant account ID


Example 1A:  Generating a token as part of a contactbooking with invoice creation

One way to get the first two is to generate a new booking and invoice using insert complex contactbooking


POST /beacon/service.svc/insert/complex/contactbooking HTTP/1.1
Host: data.peak15systems.com
Content-Type: application/x-www-form-urlencoded

token=your-token-here
&contact.firstname=testFName
&contact.lastname=testLName
&contact.emailaddress1=test%40tester.com
&contact.p15_contacttype_contactid=Client
&p15_bookings.p15_tripdepartures_bookingsid=42FBF5CD-73D9-ED11-80DE-00155D027062
&p15_guests.contact.1.isClient=true
&contact.address1_line1=123%20Test%20St.
&contact.address1_city=Testtown
&contact.address1_stateorprovince=CO
&contact.address1_postalcode=55501
&contact.address1_country=US
&p15_invoices.p15_paymentscheduleid=36AE83A1-5878-E111-A0D9-0050568B0004
&returnfullsteamtoken=1


Note that in this case, unlike in a standard Stripe Checkout or Cybersource Secure Acceptance scenario, we are not including the amount, currency or successpage parameter.  That is because this example doesn’t involve a redirect and thus allows the developer to more directly control the behavior.


The last param in these calls, which is returnfullsteamtoken=1, lets Beacon know it should return an encrypted beacon token along with the invoice ID that would normally return from this call. So in this case, the return might look something like:

21b4bfe4-e5de-ed11-80de-00155d027062||/1RzVmUcrDKZjZUumOfwv1AYcjo6RFS4P9NQXpLt9Ec=


The two pipes: || are the delimiter between the invoiceID in this case and the encrypted Beacon token.


The encrypted Beacon token is hashed with a timestamp that is valid for 30 minutes from the time it is issued. After that point, a postback containing an expired Beacon token will be returned with the error message of “The payment session has expired. Please resubmit your request with a current session token.” It is recommended that the Beacon token be refreshed and the payment form be called again with the refreshed Beacon token value. 


With the result, the customer’s website can then call their payments page with this result in the URL params along with the amount and merchant identifier. This might look like


https://mytravelwebsite.com/purchase?invoiceParam=21b4bfe4-e5de-ed11-80de-00155d027062||/1RzVmUcrDKZjZUumOfwv1AYcjo6RFS4P9NQXpLt9Ec=&contactId=0&amount=204&merchantIdentifier=EAC3B405-D808-4FD6-8C27-1AC6D9BFBF7B

In the above URL are the following elements

  • The invoiceParam will contain the combination of the invoiceId and the encrypted Beacon token.
  • contactId--this can be 0 in which case the client on the invoice will have the credit card used associated with them and charged. In cases where the client on the booking should not be charged, the contactId can be passed in along with the invoiceId. In cases where there is no booking and only a tokenization is intended, the contactId and the encrypted Beacon token should be passed in (see Example 2 below)
  • amount--this is the amount to be charged, it can be any amount up to the full value of the invoice. If this is set to $0, the form assumes the intent is to tokenize only and not collect payment at this time. Amount is a numeric, double precision field and cannot be passed in as null or empty.
  • merchantIdentifier--this designates the merchant account to be used for this transaction and is the fullSteamMerchantID from the Support table which is also the accountID used in the Merchant Account record in PEAK 15.  It is NOT the GUID of the Merchant Account record in PEAK 15.The customer’s page must have two elements embedded in it.


NOTE on eChecks/ACH -- If your account is setup for eChecks, the widget will default to the Credit Card option, but allow the visitor to switch to eCheck.  To have the payment widget open to the eCheck option by default, simply pass in &mode=ACH to the iframe.  There is not currently an option to control whether the eCheck or Credit Card option is available to a specific visitor, only which one is defaulted if both are setup.


An iFrame with the id of “paymentForm”. This iFrame should have a minimum size of 850x550px.


<iframe id="paymentForm" scrolling="no" frameborder="0" 
style="width: 850px; height: 550px;  overflow: hidden;">
</iframe>

A payments.js  reference made to Beacon2. We recommend customers put a reference to the hosted .js on Beacon2 as opposed to including a local file. The reference would be simply:

<script src="https://beacon2.peak15systems.com/scripts/payments.js"></script>


This Javascript file contains a small amount of code to do two things

  • It contains the code to translate the url elements into the iFrame
  • It contains the address of the PEAK 15 payment form to be loaded into the iFrame in the src attribute so that it looks like this:


<iframe id="paymentForm" scrolling="no" frameborder="0" 
style="width: 850px; height: 550px;  overflow: hidden;"
..insert here..>
</iframe>




The resulting page will look something like this with the customer’s page content replacing “Your website header and content here”:


Everything between ← PEAK 15 Pay widget starts here → and <--PEAK 15 Pay widget ends here → is the PEAK 15 Pay iFrame content coming from Beacon2.


Within the PEAK 15 Pay iFrame, we’re further including fields directly from Fullsteam. Those fields are Card Number, Expiration Month, Expiration Year and CVV. Those fields never “touch” PEAK 15 servers, they are sent directly to Fullsteam for a secure customer experience.


When the customer fills out the form and presses continue, the transaction is sent to Fullsteam and the return from that transaction is used to create the appropriate electronic payment account and payment within PEAK 15.


Following a transaction, there’s several different ways to handle the receipt/thank you page that should follow. PEAK 15 recommends that the receipt page be fully hosted on the customer’s website. With that page specified in the merchant set up, PEAK 15 pay will redirect the iFrame (the data of which can then be sent to the parent frame) to that page with two params specified: transactionId and beaconToken. These params can be used then to call an API endpoint: getTransaction. 


POST /api/payments/getTransaction HTTP/1.1
Host: beacon2.peak15systems.com
Content-Type: application/x-www-form-urlencoded

transactionId=your-transactionid
&beaconToken=your-beacon-token

Example return:

{
    "type": "Tokenize",
    "transactionResponse": null,
    "tokenizeResponse": {
        "token": "8a617462-00c0-47f5-b909-efa353c1f3c5",
        "issuerResponseDetails": {
            "description": null,
            "issuerResponseCode": "00",
            "issuerResponseDescription": "Transaction Approved",
            "avsResponseCode": "G",
            "avsResponseDescription": "Global non-AVS participant.",
            "cvvResponseCode": "N",
            "cvvResponseDescription": "No Match",
            "authCode": "AVSE12",
            "processingNetwork": 1
        },
        "accountDetails": {
            "paymentMethod": 1,
            "cardBIN": "489528",
            "paymentAccountLast4": "0006",
            "nameOnAccount": "Test Card",
            "expirationMonth": 12,
            "expirationYear": 2025,
            "commercialCardCustomerCode": null,
            "cardBalanceAmount": 0.0,
            "cardEntryMethod": 4,
            "routingNumber": null,
            "achAuthorizationType": 0,
            "giftCardOperationId": 0,
            "wexPdsn": null
        },
        "actionGuid": "adfc1d05-37e3-4051-9ce2-c3e67eaf02fe",
        "isSuccessful": true,
        "responseCode": 0,
        "responseDetails": [],
        "durationInMilliseconds": 308,
        "transactionId": "00000000-0000-0000-0000-000000000000",
        "responseId": "00000000-0000-0000-0000-000000000000"
    }
}

Example 1B:  Generating a token when the invoice already exists

There are scenarios where a customer has all the information already for a transaction and only requires the encrypted Beacon token to put together the URL for the payment page. Consider the case where the invoice already exists. In that case, the Beacon call to gain the encrypted token would look like this:


POST /beacon/service.svc/update/entity/p15_invoices HTTP/1.1
Host: data.peak15systems.com
Content-Type: application/x-www-form-urlencoded

token=your-token-here
&p15_invoicesid=38F4B55B-83CE-E311-8980-005056A47D9E
&returnfullsteamtoken=1

EXAMPLE 2: Tokenizing a credit card or eCheck account for a specific Contact


This example operates as above with different values passed to the page params. 


Example 2A: Generating a token as part of a contact insert


An example of this might begin with a Beacon call to insert a new contact:


POST /beacon/service.svc/insert/entity/contact HTTP/1.1
Host: data.peak15systems.com
Content-Type: application/x-www-form-urlencoded

token=your-token-here
&firstname=Test
&lastname=Test
&emailaddress1=test%40tester.com
&p15_contacttype_contactid=Client
&address1_line1=123%20Test%20St.
&address1_city=Testtown
&address1_stateorprovince=CO
&address1_postalcode=55501
&address1_country=US&returnfullsteamtoken=1

Example 2B: Generating a token as part of a contact update


Or an “empty” or non-empty update to an existing contact


POST /beacon/service.svc/update/entity/contact HTTP/1.1
Host: data.peak15systems.com
Content-Type: application/x-www-form-urlencoded

token=your-token-here
&contactid=711A2112-1AE6-ED11-80F7-00155D02B866
&returnfullsteamtoken=1


Again, we have returnfullsteamtoken=1 to ensure that the encrypted Beacon token is returned along with the contact ID generated by the insert or update. The resultant call to the customer’s page might then look like:


https://mytravelwebsite.com/purchase?invoiceParam=&contactId=21b4bfe4-e5de-ed11-80de-00155d027062||/1RzVmUcrDKZjZUumOfwv1AYcjo6RFS4P9NQXpLt9Ec=&amount=0&merchantIdentifier=EAC3B405-D808-4FD6-8C27-1AC6D9BFBF7B

In this case, the merchantIdentifier remains the same for the customer, specifying the merchant account to be used. invoiceParam is left blank and the contactId and beaconToken are included in the contactId field. Amount is set to 0 to indicate this is a tokenization only call.


NOTE on eChecks/ACH -- If your account is setup for eChecks, the widget will default to the Credit Card option, but allow the visitor to switch to eCheck.  To have the payment widget open to the eCheck option by default, simply pass in &mode=ACH to the iframe.  There is not currently an option to control whether the eCheck or Credit Card option is available to a specific visitor, only which one is defaulted if both are setup.


EXAMPLE 3: Collecting payment from a Contact other than the Client on the Invoice


When both the invoiceParam and the contactId are populated with content, this is an indicator that a charge should be done on an invoice but the client on that invoice should not be charged and, instead, the contactId specified should be charged. That will look like a combination of the two scenarios above.


https://mytravelwebsite.com/purchase?invoiceParam=invoiceParam=21b4bfe4-e5de-ed11-80de-00155d027062||/1RzVmUcrDKZjZUumOfwv1AYcjo6RFS4P9NQXpLt9Ec=&contactId=21b4bfe4-e5de-ed11-80de-00155d027062&amount=200&merchantIdentifier=EAC3B405-D808-4FD6-8C27-1AC6D9BFBF7B
NOTE: While the encrypted Beacon token can be passed in either the invoiceParam or the contactId params if a charge action is to be undertaken, the encrypted Beacon token must be passed in the invoiceParam at the very least.

EXAMPLE 4: Using redirect behavior similar to Stripe Checkout


A customer who was previously integrated with Stripe Checkout or Cybersource Secure Acceptance might have a beacon call to set it up looking like this:

POST /beacon/service.svc/insert/complex/contactbooking HTTP/1.1
Host: data.peak15systems.com
Content-Type: application/x-www-form-urlencoded

token=your-token-here
&contact.firstname=testFName
&contact.lastname=testLName
&contact.emailaddress1=test%40tester.com
&contact.address1_line1=123%20Test%20St.
&contact.address1_city=Testtown
&contact.address1_stateorprovince=CO
&contact.address1_postalcode=55501
&contact.address1_country=US
&contact.p15_contacttype_contactid=Client
&p15_bookings.p15_tripdepartures_bookingsid=42FBF5CD-73D9-ED11-80DE-00155D027062
&p15_guests.contact.1.isClient=true
&p15_invoices.p15_paymentscheduleid=36AE83A1-5878-E111-A0D9-0050568B0004
&amount=204
&currency=USD
&SuccessPage=Stripe-or-Cybersource-Redirect-here

Example 4a: Using redirect for payment and tokenization


The success page with invoiceId lets Beacon know that it needs to do a full redirect to Stripe checkout or Cybersource Secure Acceptance rather than return a response. PEAK 15 Pay has similar functionality where invoiceParam is substituted for invoiceId in that example and a value is passed. For example:


POST /beacon/service.svc/insert/complex/contactbooking HTTP/1.1
Host: data.peak15systems.com
Content-Type: application/x-www-form-urlencoded

token=your-token-here
&contact.firstname=testFName
&contact.lastname=testLName
&contact.emailaddress1=test%40tester.com
&contact.address1_line1=123%20Test%20St.
&contact.address1_city=Testtown
&contact.address1_stateorprovince=CO
&contact.address1_postalcode=55501
&contact.address1_country=US
&contact.p15_contacttype_contactid=Client
&p15_bookings.p15_tripdepartures_bookingsid=42FBF5CD-73D9-ED11-80DE-00155D027062
&p15_guests.contact.1.isClient=true
&p15_invoices.p15_paymentscheduleid=36AE83A1-5878-E111-A0D9-0050568B0004
&amount=204
&currency=USD
&returnfullsteamtoken=1
&SuccessPage=https://mytravelwebsite.com/purchase?invoiceParam

This web call will follow a PEAK 15 Pay path inside of Beacon and redirect to the success page URL with the appropriate params specified. “Purchase” in the example URL above is a page that is built to take the form params that Beacon is posting back.


NOTE on eChecks/ACH -- If your account is setup for eChecks, the widget will default to the Credit Card option, but allow the visitor to switch to eCheck.  To have the payment widget open to the eCheck option by default, simply pass in &mode=ACH in your SuccessPage URL.  There is not currently an option to control whether the eCheck or Credit Card option is available to a specific visitor, only which one is defaulted if both are setup.


Example 4b: Using redirect for account tokenization only

If you only want to tokenize the account just pass amount = 0 as below.

POST /beacon/service.svc/insert/complex/contactbooking HTTP/1.1
Host: data.peak15systems.com
Content-Type: application/x-www-form-urlencoded

token=your-token-here
&contact.firstname=testFName
&contact.lastname=testLName
&contact.emailaddress1=test%40tester.com
&contact.address1_line1=123%20Test%20St.
&contact.address1_city=Testtown
&contact.address1_stateorprovince=CO
&contact.address1_postalcode=55501
&contact.address1_country=US
&contact.p15_contacttype_contactid=Client
&p15_bookings.p15_tripdepartures_bookingsid=42FBF5CD-73D9-ED11-80DE-00155D027062
&p15_guests.contact.1.isClient=true
&p15_invoices.p15_paymentscheduleid=36AE83A1-5878-E111-A0D9-0050568B0004
&amount=204
&currency=USD
&returnfullsteamtoken=1
&SuccessPage=https://mytravelwebsite.com/purchase?invoiceParam



NOTE on eChecks/ACH -- If your account is setup for eChecks, the widget will default to the Credit Card option, but allow the visitor to switch to eCheck.  To have the payment widget open to the eCheck option by default, simply pass in &mode=ACH in your SuccessPage URL.  There is not currently an option to control whether the eCheck or Credit Card option is available to a specific visitor, only which one is defaulted if both are setup.