Implementation

Steps for Creating an Order

1. On Checkout:

   • The webshop saves the transaction in its database.

   • The status field is set to pending.

2. Set the Request Header:

   Accept: application/json

3. Make a CreateOrder POST Request:

   POST https://test.mypayloft.com/MERCHANTID

   Replace MERCHANTID with your actual Merchant ID received via email.
   You can also find your Merchant ID and Secret Key under
   Settings > API Keys on the Payloft Onboarding Platform.

4. Request Payload (JSON Format):

   { "amount": 100, "currency": 566, "description": "Your transaction description", "returnUrl": "http://yourwebsite.com/returnurl", "callbackUrl": "https://youwebsite.com/callbackurl", "secretKey": "5ASD599DFSA21SDS13S536SFS98968390", "fee": 0, "referenceID": "YourPaymentReference", "CustomerName": "Customer Name", "Email": "customeremail@domain.com", "isJson": "false" }

5. Refer to Table 1.0 for field details.

6. Replace secretKey with the cryptographic key sent to you via email.

7. Ensure that the currency follows the ISO 4217 numeric standard.

8. The amount displayed to the customer must match the amount sent to the payment gateway.

9. returnUrl: The URL where Payloft redirects the customer after payment.

10. callbackUrl: The URL your server is notified on after payment completion.

11. isJson: Determines the response format:

    • true → Data is returned via GET

    • false (default) → Data is returned via POST

12. referenceID Your own Transaction reference ID

13. You can include metadata such as your transaction ID, customer IP address, or other info in the description field.
    Example:

    "description": "Description of service^REF:123456(IP:41.8.29.132)"

Table 1.0

Process Overview

1. Receiving the Create Order Request:

   • When a Create Order request is submitted, the Payloft Gateway (UP MPI) captures the following transaction details:

     • amount

     • description

     • secretKey (cryptographic key)

     • Additional fields from the payload

2. Generating the Transaction ID:

   • The gateway creates a session with the submitted data.

   • A unique transaction ID is generated to represent the transaction.

   • This transaction ID is included in the response to the Create Order request.

3. Usage of the Transaction ID:

   • This ID must be included in all subsequent requests, such as:

     • Payment initiation

     • Transaction status queries

   • The webshop must store and use this ID for all operations related to the transaction.

4. Querying Transaction Details:

   • The Payloft Gateway uses the transaction ID to look up and return the transaction's current status and details.

1. Update Webshop Database

• Persist the Transaction ID returned in the Create Order response.

• Link the transaction ID to the relevant order record in your webshop’s database.

2. Redirect Customer to Payloft for Payment

• Initiate an HTTP GET request to redirect the customer to the payment gateway.

• Include the Order ID as part of the URL path.

Definition

A 3DSecure Provider is an entity responsible for delivering 3DSecure authentication services, which help verify the identity of cardholders during online transactions.

Role of a 3DSecure Provider

A 3DSecure Provider can be:

• A payment scheme such as:

  • Visa

  • Mastercard

  • Verve

• A third-party service provider acting on behalf of the card Issuer.

Purpose

3DSecure authentication enhances the security of online card payments by reducing the risk of fraud through additional customer verification steps.

Table 2.0

Table 3.0

1. Verifying Payment Notification via x-api-key Header

When a payment is completed or updated, the Payloft Gateway (UP MPI) sends a POST request to your configured callbackUrl. This request includes:

• A header (x-api-key) containing your secretKey

• A JSON body with the transaction data

2. Header Information

The signature is included in the x-api-key header of the callback POST request.