First Payment Merchant Services
Credentials:
username: username
password: password
This is a plugin which can be used to make credit/debit card payments and refunds in the UK which reach bank accounts much more quickly than Stripe (which as of June 2020 has a 7 calendar day payout delay).
Contact [email protected] to add the plugin to your app.
Contact First Payment Merchant Services to set up the bank account details and such, which seems to be a fairly manual process on their end.
Hosted docs
Cardstream FPMS Hosted Guide-v9.16b (1).pdf
2MB
PDF
Direct integration docs
Cardstream FPMS Direct Guide-v9.16b.pdf
2MB
PDF
Here are some details about the API calls set up as JavaScript actions in the plugin.
Both of these calls return HTML which can be used to set up a payments gateway on the page in an iFrame.
Charge a card for a transaction immediately. This also generates a card token that can be used for future transactions.
Doing a "Preauth" call puts a hold on money but doesn't ever charge anything to the card. For example, someone orders a $15 dish and enters their credit card info. A "preauth" call for $1 is done to check that their card actually has the ability to pay at least $1 (but not $15 since we don't want to tie up their credit, since when we charge them later it will issue a second $15 hold on funds from their account). Then, after they have checked out, the card token returned by this Preauth call can be used to charge the card via the Sale (card on file) call.
Inputs:
- Merchant ID: needs to be gotten from a FPMS representative. Use 101118 as a test ID. Assigned in the plugins tab.
- Key: secret key used for authentication. Assigned in the plugins tab. When using 101118 as a test ID, use Answer10Dispute4Follow as the test key.
- Amount: amount to send. For test cards, values over £50 will fail ("referred card" failure), and values over £100 will be declined.
- Order reference (to record some information for the merchant's records)
- Transaction unique ID (some unique ID to send with the transaction). Hexadecimal number. The sample calls use 13 digits (all values must be either 0-9 or a-f, something like abc1231cf or 1234), but it's unclear if that's a requirement.
- Callback URL (optional): URL that will receive a POST of the data from the transaction. Can use an API Workflow for this.
- Redirect URL: URL to which the iFrame will be redirected after the transaction. It will also send a POST with all the data from the transaction. Because this is a POST request and not a GET request, it should be an API Workflow that redirects the user to a Bubble page.
Outputs:
- Presigned Request: Field for debugging. Contains the string which is signed. Useful for debugging any error messages complaining about the signature (response code 66343).
- Response Dump: raw text of the JSON returned by the API.
- HTTP Status Code: The status code returned by the API. For this API, almost always a 20X (Success) return, even if the SALE or other action was not successful.
- Request Dump: raw text of the JSON sent to the API.
- Response Body: raw text of the JSON body returned by the API. For Hosted calls, this is the most important field: this text is an HTML that is used to later process the transaction.
Callback Outputs (not a complete list):
- Presigned Request: Field for debugging. Contains the string which is signed. Useful for debugging any error messages complaining about the signature (response code 66343).
- Success: yes/no saying if the request was successful.
- Response Dump: raw text of the JSON returned by the API.
- HTTP Status Code: The status code returned by the API. For this API, almost always a 20X (Success) return, even if the SALE or other action was not successful.
- Request Dump: raw text of the JSON sent to the API.
- Response Body: raw text of the JSON body returned by the API.
- avscv2ResponseMessage: CVV and Address validity response (human readable text).
- cv2Check: CVV validity check (returns "matched" or "not matched").
- addressCheck: Address validity check. Possible values are: not known, not checked, matched, not matched, partially matched. (Usually returns matched, not matched, or partially matched.)
- postcodeCheck: Post code validity check. Possible values are: not known, not checked, matched, not matched, partially matched. (Usually returns matched, not matched, or partially matched.)
- amountApproved: Amount approved by the call. If this isn't the same as the amount requested, it's likely there's an issue (which would also be flagged by the response code).
- amountReceived: Amount received by the merchant.
- transactionID: The transaction ID assigned by the system. NOT the same as the Transaction Unique ID sent when creating the call.
- xref: A code that can later be used for other API calls, like querying the status of the transaction or refunding the transaction.
- responseCode: Gives a 0 when successful. Returns some other code if the API call fails. More information about what the response code means can be found in the docs linked to at the bottom of this page.
- responseMessage: Message explaining whether the API call was successful, or explaining what the response code means if it failed.
- responseStatus: may be unnecessary, but returned by the first payments API.
Verification of the CVV (3 digits on back of card) and address can be set up as an optional part of this transaction.
A response code of 0 is returned for a successful call. All other calls are unsuccessful (either for a denied payment or a "referred" card).
Create the payment gateway
Process the HTML and display it in a group
Copy and paste the above "find and replace" text to display the HTML. It intentionally isn't set up in the JavaScript code because the HTML response from FPMS could change at some point and it's more flexible to process this logic on the Bubble side (assuming more AirDev people have Bubble knowledge than JavaScript knowledge, as well as less people having access to the plugin code).
Screenshot of the payment iFrame
API Workflow to be sent to the Redirect URL input
Return data as a URL querystring along with the redirected page
More info about post redirects here:
The callback may be unnecessary, as the redirect receives all the same information and the first steps in the redirect flow (before returning data) can also write data to the Bubble database or carry out other actions, like email alerts.
Automatically detect data to set up this call with all of the response data
Save some response data or use it for notifications
This refunds a specific purchase. Differs from Refund in that it MUST refer to a specific purchase.
Refers to the "xref" field returned by a hosted call.
This credits a certain amount to a card. No relation to any previous transaction/sale is necessary.
Refers to the "xref" field returned by a hosted call.
From the First Payment docs:
This will cancel an existing transaction, identified using the xref request field, preventing it from being settled. It can only be performed on transactions which have been authorised but not yet settled, and it is not reversible. Depending on the Acquirer it may not reverse the authorisation and release any reserved funds on the cardholder’s account, in such cases authorisation will be left to expire as normal releasing the reserved funds – this may take up to 30 days from the date of authorisation.
Acquirer refers to an organization that processes payments.
Last modified 3yr ago