Initialisation

The Initialisation step creates a new transaction on the Payen platform and returns a requestKey that is used to continue the APM flow. The merchant performs a server-to-server POST request to the platform.

POST https://pripframev2.trustpayglobal.com/ipframe/apm/initialise

Request

The request must be sent server-to-server from the merchant backend to the Payen platform.

Property	Value
Method	POST
Content-Type	application/json or text/xml
Encoding	UTF-8
Transport	HTTPS
Authentication	Digest header

A digest header must be included with the request. For details on how to generate the digest, see the Digest Calculation section.

Example Request

JSON

Initialisation Request example

{
    "version": 2,
    "merchant": {
        "merchantId": "10000001",
        "accountId": "20000001"
    },
    "customer": {
        "customerId": "1",
        "email": "[email protected]",
        "firstName": "Test",
        "surname": "Client",
        "dateOfBirth": "03042000",
        "address": {
            "addressLine1": "123 Street",
            "city": "Guildford",
            "province": "Surrey",
            "postcode": "GU2 2YG",
            "country": "GBR"
    },
    "identityDocumentNumber": "20130110123456789",
    "identityDocumentType": "IDENTITY_CARD",
    "mobileNumber": "01234123123"
    },
    "transaction": {
        "amount": 1000,
        "currency": "USD",
        "merchantRef": "Fh8F9fEpeK8qUFMHt0Vl"
    },
    "url": {
        "responseUrl": "https://www.url.com/payment/response",
        "notificationUrl": "https://www.url.com/payment/notification",
        "thirdPartySuccessUrl": "http://www.url.com/payment/success",
        "thirdPartyCancelUrl": "http://www.url.com/payment/cancel"
    },
    "paymentInfo": {
        "country": "GBR"
    }
}

XML

Initialisation Request example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<initialisationRequest>
    <version>2</version>
    <merchant>
        <merchantId>10000001</merchantId>
        <accountId>20000001</accountId>
    </merchant>
    <customer>
        <customerId>1</customerId>
        <email>[email protected]</email>
        <firstName>Test</firstName>
        <surname>Client</surname>
        <dateOfBirth>03042000</dateOfBirth>
        <address>
            <addressLine1>123 Street</addressLine1>
            <city>Guildford</city>
            <province>Surrey</province>
            <postcode>GU2 2YG</postcode>
            <country>GBR</country>
        </address>
        <identityDocumentNumber>20130110123456789</identityDocumentNumber>
        <identityDocumentType>IDENTITY_CARD</identityDocumentType>
        <mobileNumber>01234123123</mobileNumber>
    </customer>
    <transaction>
        <amount>1000</amount>
        <currency>USD</currency>
        <merchantRef>Fh8F9fEpeK8qUFMHt0Vl</merchantRef>
    </transaction>
    <url>
        <responseUrl>https://www.url.com/payment/response</responseUrl>
        <notificationUrl>https://www.url.com/payment/notification</notificationUrl>
        <thirdPartySuccessUrl>http://www.url.com/payment/success</thirdPartySuccessUrl>
        <thirdPartyCancelUrl>http://www.url.com/payment/cancel</thirdPartyCancelUrl>
    </url>
    <paymentInfo>
        <country>GBR</country>
    </paymentInfo>
</initialisationRequest>

Response

If the request is valid, the platform creates the transaction and returns a requestKey.

This key identifies the transaction and must be included in the subsequent APM Process request.

Example response

JSON

Initialisation Response example

{
    "version": 2,
    "merchant": {
    "merchantId": "10000001",
    "accountId": "20000001"
},
    "transaction": {
    "merchantRef": "Fh8F9fEpeK8qUFMHt0Vl",
    "gatewayRef": "G78GYft76HGJ98IOifT"
},
    "status": {
    "code": "SUCCESS",
    "timestamp": "2012-06-21T16:56:39.154+01:00"
},
    "requestKey": "3b5bee9ffa8a446e8f30161516af1527"
}

XML

Initialisation Response example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request>
    <version>2</version>
    <merchant>
        <merchantId>10000001</merchantId>
        <accountId>20000001</accountId>
    </merchant>
    <transaction>
        <merchantRef>Fh8F9fEpeK8qUFMHt0Vl</merchantRef>
        <gatewayRef>G78GYft76HGJ98IOifT</gatewayRef>
    </transaction>
    <status>
        <code>SUCCESS</code>
        <timestamp>2012-06-21T16:56:39.154+01:00</timestamp>
    </status>
    <requestKey>3b5bee9ffa8a446e8f30161516af1527</requestKey>
</request>

Merchant Responsibilities

After receiving a successful response:

• Store the requestKey associated with the merchant order.
• Use the requestKey when calling the APM Process endpoint.
• Continue the APM flow.

Next Step

Once the transaction has been initialised and the requestKey obtained, the merchant must start the payment by submitting the customer’s browser to the APM Process endpoint at /ipframe/apm/process.

To do this, the merchant should:

1. Construct a form that will be submitted via the customer’s browser. The form must include:

• requestKey – returned from the initialisation step
• merchantId – the merchant identifier
• digest – an authentication digest calculated over the form data, as described in the Digest Calculation section

2. Submit the form via the customer’s browser. This ensures the payment flow is handled directly between the browser, the Payen platform, and the APM provider without passing through the merchant server.

3. Platform processing:

• The platform validates the request and digest.
• Retrieves the transaction associated with the requestKey.
• Determines the correct APM provider and initiates the payment.

4. Browser redirect: After processing, the Payen platform responds with a redirect that sends the customer to the third-party APM provider’s payment page, where the customer completes the payment securely.

This flow allows the merchant to initiate the payment while never handling sensitive payment data directly. The final payment status will be made available to the merchant through the server-to-server notification or by querying the status API using the responseKey.