RECURRING PAYMENTS

PPRO supports recurring charges to a consumer's account through the use of an AGREEMENTID in the following steps:

Create an agreement through the new AGREEMENT API call. After receiving the redirect secret in the response, redirect the consumer so that they can activate the agreement;
Receive a notification and check that the agreement is active using GETAGREEMENTSTATUS API call;
Create subsequent transactions without needing consumer interaction, simply by passing the AGREEMENTID when you make a TRANSACTION call;
Additionally, using the new GETAGREEMENTTXSTATUS endpoint, you can retrieve a list of all transactions associated with a particular recurring AGREEMENT.

1. AGREEMENT

This request allows you to create the agreement needed to make recurring transactions. The following input fields are supported:

1.1 AGREEMENT - Call input

tag=twint
&txtype=AGREEMENT
&login=johndoetest
&password=***
&contractid=JOHNDOETESTCONTRACT
&accountholdername=John%20Doe
&channel=testchannel
&countrycode=CH
&merchantredirecturl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2F...
&notificationurl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2F...
&initialtransactionmerchanttxid=23234905435
&initialtransactionisocurrency=CHF
&initialtransactionamount=100
&returnmode=urlencodeext

Most of the fields should appear familiar from the standard TRANSACTION call. Including the initialtransaction* fields facilitate a flow where the consumer pays the first amount at checkout, and simultaneously sets up an agreement to be charged on a recurring basis. If you want to create an agreement without immediately charging the consumer, you should leave these fields out of your request.

Regarding the initialtransaction* fields:

Input Field	Mandatory / Optional	Description
`initialtransactionmerchanttxid`	O	Same format as `merchanttxid` in a `TRANSACTION` request.
`initialtransactionamount`	O	Same format as `amount` in a `TRANSACTION` request.
`initialtransactionisocurrency`	O	Same format as `currency` in a `TRANSACTION` request.

1.2 AGREEMENT - Call Output

&AGREEMENTID=1000000615
&CHANNEL=testchannel
&ERRMSG=
&INITIALTRANSACTIONID=150000677215
&MERCHANTAGREEMENTID=
&RAND950428166=c6f00e74a614675e384ca5e89d74a19d0413c0a0
&REDIRECTSECRET=s2TRzVw0mVBBNXLFpOEQaL4A7NWLSYAE
&REDIRECTURL=https%3A%2F%2Fauthman%2Eqa%2Elp%2Dpl%2Eppro%2Ecom%2Fv0%2Fredirections%2Fforward%3Fredirection%5Ftoken%3De...
&STATUS=PENDING
&TAG=twint

The main differences compared to a TRANSACTION response are the new fields AGREEMENTID, and INITIALTRANSACTIONID.

Output Field	Description
`AGREEMENTID`	The id of the persisted agreement – Example: 1000000615.
`INITIALTRANSACTIONID`	The id of the persisted transaction – Example: 150000677215.
`STATUS`	Enum with possible values: PENDING ACTIVE FAILED REVOKED_BY_CONSUMER REVOKED_BY_MERCHANT

You will need to store the value of AGREEMENTID so you can pass it in future TRANSACTION calls once the STATUS is ACTIVE.

1.3 Activating the Agreement

In the AGREEMENT call output, exists the REDIRECTSECRET value. Use this to validate the REDIRECTURL we provide and send the consumer to a page hosted by the payment scheme, where they will complete an authentication flow and accept the agreement.

Once the successful acceptance of the agreement is communicated to PPRO by the scheme, we change the STATUS to ACTIVE and send you a notification. At this time, the agreement status to confirm it is ACTIVE.

2. GETAGREEMENTSTATUS

Use this operation to get the latest status of the AGREEMENT.

2.1 GETAGREEMENTSTATUS - Call Input

txtype=GETAGREEMENTSTATUS
&login=johndoetest
&password=***
&contractid=JOHNDOETESTCONTRACT
&agreementid=1000000625
&returnmode=urlencodeext

The AGREEMENTID value returned in the AGREEMENT call.

Input Field	Mandatory / Optional	Description
`agreementid`	M	The `agreementid` value returned in the `AGREEMENT` call.

2.2 GETAGREEMENTSTATUS - Call Output

The response structure is identical to the AGREEMENT call output.

AGREEMENTID=1000000626  
&CHANNEL=testchannel  
&ERRMSG=  
&INITIALTRANSACTIONID=150000677226  
&MERCHANTAGREEMENTID=  
&RAND4213655405=da0209f0cedbce967ceea243534ba809de5aeec4  
&REDIRECTSECRET=2KIbkd7pWlJDnok70dfjAil3achLOvVV  
&REDIRECTURL=<https://authman.qa.lp-pl.ppro.com/v0/redirections/forward?redirection_token=>...  
&STATUS=ACTIVE  
&TAG=twint

3. TRANSACTION

Once you confirm an agreement is ACTIVE, you can pass the agreementid value when you make a TRANSACTION request. Please note that the payment method used must support recurring payments for this flow to work.

The request structure is the same as a TRANSACTION call input for the payment method in question, plus this added agreementid field.

In the TRANSACTION call output, you should see that the recurring payment succeeds immediately without the need to redirect / authenticate the consumer.

3.1 TRANSACTION - Call Input

tag=twint  
&txtype=TRANSACTION  
&login=johndoetest  
&password=***  
&contractid=JOHNDOETESTCONTRACT  
&accountholdername=John%20Doe  
&channel=testchannel  
&countrycode=CH  
&returnmode=urlencodeext  
&amount=100  
&currency=CHF  
&agreementid=1000000625  
&merchantredirecturl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2F...  
&merchanttxid=53498e0a-50be-4bad-bf99-6a071073b218

3.1 TRANSACTION - Call Output

CHANNEL=testchannel  
&ERRMSG=  
&FLAGS=  
&FUNDSSTATUS=WAITING  
&MERCHANTTXID=13169f2d-23cf-40ec-b021-aede85b0e71b  
&RAND298712208=e20ea7c9e4eec0bbfd2273aefea62a440e047553  
&REDIRECTSECRET=VJLuKDumJjTRKJsssBR26VorKNEE4g2v  
&REDIRECTURL=<https://authman.qa.lp-pl.ppro.com/v0/redirections/forward?redirection_token=>...  
&SPECOUT.PROVIDERORDERSTATUS=IN_PROGRESS  
&SPECOUT.PROVIDERORDERSTATUSCODE=1  
&SPECOUT.PROVIDERORDERSTATUSREASON=ORDER_RECEIVED  
&SPECOUT.PROVIDERORDERSTATUSREASONCODE=80  
&STATUS=PENDING  
&TAG=twint  
&TXID=150000677228

4. GETAGREEMENTTXSTATUS

You can use this new endpoint to get a list of all transactions made with a specified agreement.

4.1 GETAGREEMENTTXSTATUS - Call Input

txtype=GETAGREEMENTTXSTATUS  
&login=johndoetest  
&password=wXBrpVporFVjGO4R  
&contractid=JOHNDOETESTCONTRACT  
&agreementid=10000  
&page=  
&returnmode=json

Input Field	Mandatory / Optional	Description
`agreementid`	M	The `agreementid` value returned in the `AGREEMENT` call.
`page`	O	The `NEXTPAGE` token returned from previous calls to this endpoint, if the transaction list was paginated.

4.2 GETAGREEMENTTXSTATUS - Call Output

{
  "AGREEMENTID": "1000000625",
  "CHANNEL": "testchannel",
  "ERRMSG": "",
  "INITIALTRANSACTIONID": "150000678145",
  "MERCHANTAGREEMENTID": "",
  "NEXTPAGE": "eyJwayI6ImFncl9jaDd1ZUFVRFMxQVVHVjV3b2d...",
  "RAND4277473235": "3652e048765e327f9ac55189a9c3c4fe0638f3c5",
  "REDIRECTSECRET": "YtdS4cXh22J8R6iS1B1HuyOP9VdZvpAe",
  "REDIRECTURL": "https://authman.qa.lp-pl.ppro.com/v0/redirections/forward?redirection_token=...",
  "STATUS": "ACTIVE",
  "TAG": "twint",
  "TRANSACTIONS": [
    {
        "TXID":150000635350,
        "STATUS":"ACTIVE",
        "MERCHANTTXID":"53498e0a-50be-4bad-bf99-6a071073b218",
        "FUNDSSTATUS":"WAITING",
        "ERRMSG":"",
        "CHANNEL":"testchannel",
        "TAG":"mock", 
        "REDIRECTURL":"..."
      },
      {
        ...
      }
  ],
  "NEXTPAGE": "eyJwayI6ImFncl9jaDd1ZUF..."
}

Output field	Description
`TRANSACTIONS`	A list of `TRANSACTION` made under the agreement.
`NEXTPAGE`	A token that can be passed as `page` in subsequent calls to this endpoint to get the next page of transactions if the list is too long for one response.

5. CANCELAGREEMENT

This request allows you to cancel an existing agreement.

5.1 CANCELAGREEMENT - Call input

txtype=CANCELAGREEMENT
&login=johndoetest
&password=password
&contractid=JOHNDOETESTCONTRACT
&agreementid=10000
&returnmode=json

Input Field	Mandatory / Optional	Description
`agreementid`	M	The `agreementid` value returned in the `AGREEMENT` call

5.2 CANCELAGREEMENT - Call output

The response structure is identical to the AGREEMENT call output but with a REVOKED_BY_MERCHANT status.

Notifications

PPRO sends notifications when the agreement status changes. The notification payload contains the agreementid as well as the other standard notification fields.

Example – Agreement Status Changed Notification

agreementid=10000  
&finaltimestamp=2022-11-03T11%3A23%3A47-00%3A00  
&sha256hash=dfbcdd35ff5c418e7bd8cbd736cb2708592825fab74a46d1c6baac3884a98686

After you receive the notification, you'll need to query the GETAGREEMENTSTATUS endpoint to see the current agreement status, similar to how notifications work for TRANSACTION updates.