PRELIMINARY - Details may change

Sometimes the sale flow from website to Fieldpine and back requires Fieldpine to initiate the "complete payment now" process without waiting for normal polling to finalise the sale.

• A click and collect sale is being picked up by a customer. The store wants to finalise the payment now before the goods are taken
• A courier parcel has been prepared, and payment is to be confirmed before the courier is called.

The flow here is describing real time payment completion, ie someone is probably standing and waiting for payment confirmation. This may be the customer that is waiting too.

How it Works

• Fieldpine decides payment is required now. It generates a JSON packet with the following format

  { "data": {
      "action": "confirmpayment",
      "confirmamount": 89.50,
      "urgent": 1,
      "sequence": 1
  
      "sale": {
          "physkey": "KQKIWJ28CVDF66kS0WE",
          "externalid": " {Your-sale# goes here}",
          "totalsale": 99.50,
          "sid": 82030541,
          "payments": [
              {
                  "type": "online",
                  "amount": 89.50,
                  "originalamount": 99.50,
                  "source": 700221114,
                  "editcount": 1
              },
              {
                  "type": "voucher",
                  "amount": 10,
                  "source": 167284727
              }
          ]
      }
  }}
  

• This packet is sent in a HTTP POST request to your URL
  • The URL can be static, ( https://myserver.com/FieldpineWantingPayment ) or dynamically include static portions of the sale ( https://myserver.com/FieldpineWantingPayment/KQKIWJ28CVDF66kS0WE )
  • The request is sent using a POST method
  • The Content-Type header will be set to "application/json"
  • Custom HTTP headers may be included if required (eg API Key)
• Your server determines the payment to be applied (89.50 in this case, 10.00 less than original sale) and finalises payment. As as result of this payment should be taken and complete.
  • If you originally took multiple payments on the sale, you may need to determine exactly which payment is being confirmed at this time. See below for more details
• When payment is accepted OK, your server returns the following response

  { "data": {
      "status": "ok"
  }}
  
  

  Other response formats are acceptable as well, see below.

Process Flow

1	Website creates original sale	» Sale sent to Retailers server »	Fieldpine creates the sale and returns a "physkey" for this sale. This uniquely identifies this specific sale
2			Store performs checking / picking / packing
3			Store finalises sale ready for pickup or dispatch
4		« Fieldpine send "confirmpayment" to website «
5	Website processes and finalises the payment request
6		» Payment Status sent to Retailers server »	Fieldpine completes the sale and advises store / staff

Steps 4 to 6 may be repeated multiple times and you need to handle a repeat request (Step #4) for a payment that has already been completed

Your Response Format

If the payment is successful, your website returns the following packet to the original POST request, with an HTTP status of 200/OK

TBD.

HTTP Response Code

The HTTP response code is only used to indicate success/failure of the protocol, not the payment status. Both "yes payment received" and "no payment not received" will respond with 200/OK responses.

How Fieldpine interprets HTTP response codes

HTTP	Fieldpine Action
200 / OK	Reads reply body and determines payment status
201 / Created 202 / Accepted	Taken as "pending", and will retry again shortly
400 / Bad Request	Treated as payment failure, logged for technical investigation. You should only return this is you do not accept the request we sent at a technical level. (ie fields are missing etc)
5xx	Pause and retry

Security and Authentication

You should provide an HTTPS endpoint. Standard HTTP works but should be limited to dev environments.

The URL itself can be anything, we suggest a long sequence of semi random characters rather than small and obvious eg use /gjwo3htbhv/FieldpinePaymentRequest_fj2h0944hg0chebib093h5bubgwgb5ggy rather than just /FieldpinePaymentRequest

Our requests can include custom headers for API-Keys

You are welcome to implement whatever IP level security you want. However, these requests may come from stores directly or Fieldpine servers so the source IP address may not be fixed. IP Geo blocking should be fine in most cases

Our payload has the sale.physkey, which was returned on the original sale create from us.

Our payload will include any "randompassword" you specified in your original sale request. The random password field is primarily for customer level entry but it does also prove who we are

As this API is only finalising pre existing payments, the risk are more around disruption and denial of service. This API does not even include any details of which credit card # (etc) are to be charged.

You can query Fieldpine servers to verify this payment request if you wish, (exact process not publically documented) eg

• Fieldpine sends confirmpayment to you
• Your server contacts your primary Fieldpine server and verifies the sale status
• If acceptable, you complete the confirmpayment process

You may implement velocity controls (ie slowing requests down under volume), but we do ask that you limit by GEO country or IP address. Attackers are unlikely to be in the same GEO country as the retailer.

Errors and Retries

The confirm payment request is stateless, ie there is no reference number for the request, and retries under error conditions cause Fieldpine to simply issue the request again. For a repeat request you should return the same result as the original request.

Your logic is probably something like:

1. Receive confirmpayment request.
2. Extract the sale# and sequence
3. Check to see if this sale/sequence pair is already done, and send that reply again.
4. Internally mark "completion in progress"
5. Perform whatever action to finalise the payment
6. Build the response, and save that for any future repeat requests
7. Send the response as a reply to the request

To be really clear. Fieldpine can issue the same request (same sale# and sequence#) multiple times, even days apart, and you should return the result of the payment. A repeat request from Fieldpine does not mean to try again. For a retry, Fieldpine will increase the sequence#

Fieldpine only require the most recent sequence number, you do not need to keep track of every sequence requested.