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
&initialtransactioncurrency=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 initialtransation fields:_

Input Field	Mandatory / Optional	Description
INTIALTRANSACTIONMERCHANTTRANSACTIONID	O	Same format as merchanttxid in a TRANSACTION request.
INITIALTRANSACTIONAMOUNT	O	Same format as amount in a TRANSACTION request.
INITILTRANSACTIONCURRENCY	O	Same format as currency in a TRANSACTION reques

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,

Output Field	Description
AGREEMENTID	The id of the persisted agreement – Example: 1000000615.
INITIALTRANSACTIONID	The id of the persisted transaction – Example: 150000677215.
AGREEMENTSTATUS	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 AGREEMENTSTATUS 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 AGREEMENTSTATUS 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 AGREEEMENTID value returned in the AGREEMENT call.

Input Field	Mandatory / Optional	Description
AGREEMENTID	M	The AGREEEMENTID 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  
¤cy=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
AGREEEMENTID	M	The AGREEEMENTID 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

TRANSACTIONS=[
  {
      "TXID":150000635350,
      "STATUS":"SUCCEEDED",
      "FAILREASON":"INVALID",
      "MERCHANTTXID":"53498e0a-50be-4bad-bf99-6a071073b218",
      "FUNDSSTATUS":"WAITING",
      "ERRMSG":"",
      "CHANNEL":"testchannel",
      "TAG":"mock", 
"REDIRECTURL":"..."
  },
  {
    ...
  }
]
NEXTPAGE=sSD22i3jfDS2fjkjsJ

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
AGREEEMENTID	M	The AGREEEMENTID 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.