This document focuses on the endpoints that needs to be called in the Purchase Order Service (POS) and Payment Service (
PS) to sign up for a new service and make upfront payment. Calls to other related services are excluded.
The flow documented here is based on the current signup using the Client Interface and are subject to change.
Coverage and Product Selection
After navigating to the Coverage & Products, searching the address and selecting the relevant package, the Checkout page
is loaded which requires calling a POS endpoint for the relevant product’s billing scheme, passing the previously
selected productId.
The user then proceeds to enter their details, make their deferred payment selection, and click “Add Credit Card”. The
user’s customer is created at this point with their login credentials as entered. This action is followed by a call to
POS that includes the newly created customerId in the payload:
The above step creates a medium with medium_detail_id that is required for future actions.
Start Card Capturing
As some clients use Peach Payments as credit card provider, it is required to start the card tokenization process with the
following purchase order service call:
This information is required to generate the card capture form. Take care to include the previously obtained
medium_detail_id in your ShopperRedirectUrl, so that it is available when Peach Payments redirects after form
submission.
Tokenization
The following call to the POS updates the medium created earlier with the relevant token information, using the
ResourcePath parameter that Peach Payments include in the redirect url.
{"descriptor":"NNN Checkout 9041.3499.0912","recurring_type":"INITIAL","card":{"bin":"424242","bin_country":"GB","last4_digits":"4242","holder":"test1234","expiry_month":"06","expiry_year":"2026"},"customer":{"ip":"160.0.198.182","ip_country":"ZA"},"custom_parameters":{"standing_instruction_api":"true","ctpe_descriptor_template":"${INVOICE_ID} ${CHANNEL_NAME} ${SHORT_ID}","stored_credential_type":"CIT","standing_instruction":"UNSCHEDULED","shopper_end_to_end_identity":"d3bb86590fdd9b7f9a3322cdca02f61c203c161755139ddc541733d3c6f90f85"},"risk":{"score":"0"},"standing_instruction":{"source":"CIT","type":"UNSCHEDULED","mode":"INITIAL","initial_transaction_id":"{E5516170-7BE4-4B99-91A2-A38D7E3E4426}"},"result_details":{"connector_tx_i_d1":"{E5516170-7BE4-4B99-91A2-A38D7E3E4426}","connector_tx_i_d2":"{ADE5D9F2-7CD0-431E-BA4E-2DA4EAC67D93}|9041.3499.0912","connector_tx_i_d3":null,"action_code":null,"issuer_network_action_code":null,"scheme_transaction_id":null,"extended_description":null,"clearing_institute_name":null,"token_ch":null,"token_by":null,"status_details":null,"acquirer_response":"0","draft_capture_flag":null},"three_d_secure":{"eci":"07","verification_id":null,"xid":null,"pa_res":null},"is_medium_valid":null,"error_message":null,"result":{"code":"000.100.110","description":"Request successfully processed in 'Merchant in Integrator Test Mode'"},"build_number":"3991bdf112fb62e208d5ec70cd98435b5afb1ed0@2023-11-22 00:52:28 +0000","timestamp":"2023-11-22T08:21:53+00:00","ndc":"7C9A06D7BC7A2BEB0280B837D6F97EAF.uat01-vm-tx03","id":"8ac7a4a18bf3f213018bf61f13df1a98","base_url":null,"registration_id":"8ac7a4a28bf3f48b018bf61f135f1686","payment_type":"PA","payment_brand":"VISA","amount":"1.00","currency":"ZAR","merchant_transaction_id":"R4ULKKTAO76H5UTD"}
Should the card fail to tokenize, the user must then retry and not allowed to continue order placement without a valid
tokenized credit card.
Place Order
Once credit card tokenization is complete, the user selects their preferred debit day and continue with placing their
order for service. The options of the available debit days to select from is found in the product’s billing scheme:
recurrence_scheme.allowed_days.
Order placement actions the following chained calls:
Full Service call to ISP Interface
Details and actions call to POS
Update debit day call to POS
Update plan payment medium call to POS
Details and actions call to POS
Submit purchase for collection call to POS
Full Service Call to ISP Interface
This call creates the service with its serviceID, required for all subsequent actions.
This call gets the full details and available actions from POS. If POS is not yet aware of the newly created service
(which it gets notified of via SQS messages), it will trigger a discovery event to get all relative information from FNO.
After the debit day and payment medium calls are done, this call is repeated to get the correct upfront purchase under must_pay_info, to be submitted for collection.
{"type":"error:purchase-order","title":"PurchaseOrder","status":500,"detail":"Payment day cannot be changed due to billing scheme payment day frequency cap being hit.","instance":"/services/E14C231D-5899-44BE-B7A1-AA46893C8D83/debit-day/15"}
{"new_payment_amount":null,"new_payment_date":null,"pro_rata_amount":null,"pro_rata_days":null,"result":"Payment day changed for service E14C231D-5899-44BE-B7A1-AA46893C8D83"}
Update Plan Payment Medium Call to POS
This call to POS updates the plan with the medium detail id that was created and selected earlier. This medium will be used for every recurring debit run purchase.
{"result":"Plan with id 3e0ddf82-8912-459a-a6ec-f6640fdf8206 updated with medium detail id f3fe1a0a-c27b-4860-8159-6b94eb4c608d"}
Submit Upfront Purchase For Collection Call to POS
After again calling 'Get Service Details and Actions', use the purchase contained in must_pay_info and submit it to POS for collection.
NOTE: this is only executed if upfront payment via Credit Card was selected.
Success of this call should be followed by relevant success page, upload of RICA documents and a view of purchase
history.
Payment Link Medium
When the operator has payment links enabled as a payment option, the payment link is generated by the POS so that when this medium is selected for payment,
the user is redirected to the payment page to complete their payment. This payment link medium is automatically generated for the customer after placing an order.
The POST call mentioned above (Submit Purchase For Collection) will contain a URL in the response that the user can be redirected to for payment:
Create a New Medium with Existing Medium Information
TO BE DEVELOPED
A new medium is created against an existing customer using existing payment information like a credit card token. Note
that this is not part of the signup flow, but rather an alternative way to persist an existing token that was created
outside the payment system against an existing user.
The Details.ProviderInfo.Info value contains dynamic information proprietary to the
specific TPPP implementation. For this implementation, all that is required for Peach Payments are the RegistrationId,
which is the token for the card.
When the operator has PayFast as a payment provider, the payment link is generated by the POS so that when this medium is selected for payment,
the user is redirected to the PayFast payment page to complete their payment. This payment link medium is automatically generated for the customer after placing an order.
The following POST call is made to the POS to generate the payment link medium manually: