Library OpenApi Overview About these APIs Architecture Authentication Error Responses Locating a Server Sessions Design Guides Guides and Hints Examples Pricing for Websites Accepting Vouchers PreAuth Payment Replication Common Apis The most used APIs Create New Sale Payment Completion Multiple Locations Delivery Addresses Create New Sale v2 Customers Locations Products Staff WebHooks eCommerce Apis These APIs are often used with eCommerce website integrations Get Pricing Card Inquiry Report & Analysis Grouped or analysed report data. Typically used to build reports and dashboards Today Login Access Pinboard ReportRequest Advanced Information More indepth information Caller Handling HTTP Protocol Bulk Data Downloads Document Uploading RetailConfig Under Development Details of APIs that will be available shortly. Documentation provided is for early adopters Get Receipt

Payment Completion

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.

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

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


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

HTTPFieldpine Action
200 / OKReads reply body and determines payment status
201 / Created
202 / Accepted
Taken as "pending", and will retry again shortly
400 / Bad RequestTreated 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)
5xxPause 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

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.