Webhook events

Different types of events can be sent by AgoraPay.

You are free to expose a single REST endpoint URL for multiple events or to deploy different endpoint URLs, one for each type.

To gain a better understanding of these events go to the needed section :

Operation V2
Operation V3
Payment Method Alias to get IBAN
Mandate
Unpaid
Report
Abandoned Shopping Cart
Account Holder Registration

Webhook events have the following characteristics:

All events are sent to your server as a POST request with a JSON payload
Each event is sent with a "Request Body":

Request Body (Operation V3)

Copy

Copied

{
   "amount":"5.00",
   "authNumber":"462242",
   "commissionAmount":"0.05",
   "contractRef":"2102019",
   "currencyCode":"EUR",
   "eventCode":"operation",
   "eventStatusLabel":"None",
   "exchangeFees":"0.00",
   "maskedPAN":"**************91",
   "metaData":
     {
       "metadata":" "
     },
   "operationDate":"20240731",
   "operationSide":"1",
   "operationStatus":"R",
   "operationType":"1",
   "orderRef":"Spadaro-2024-07-31 11:43:34",
   "paymentFees":"0.00",
   "paymentMethodTypeId":"4",
   "relatedMsgStatus":"0",
   "schemeFees":"0.00",
   "transRefNo":"38125957",
   "transactionId":"7562722",
   "versionNumber":"3.0"
}

Copy

Copied

Each event is sent with a "HTTP-Header":

Http-Header (Operation V3)

Copy

Copied

header: {
  "User-Agent": "AgoraPay/1.0",
  "Host": "YourMarketPlace.fr",
  "Content-Type": "application/json",
  "Content-Length": 533,
  "Authorization": "hmac 1.0/08b72fcf-97e8-4a54-866b-dad9ea7f57b7/1722427893459/00934d0f-8993-4be6-96c2-b9c2d76acec5/CBFABE34D6A05EC6072E7E93C5DF206DBFDCCE6E60BACDB83BFACB60FC41B43E"
}

Copy

Copied

Should an event fail to be transmitted to your server (i.e. your endpoint didn't send a HTTP 200 response), 2 retries with 30 seconds of interval are performed

This webhook event is sent by AgorayPay for any operation creation or change of status.

Please refer to the payin operation life cycle discussion of the financial section to see all the statuses that will trigger an update notification.

The event includes the following parameters:

Field name

Description

amount

Amount of the operation

currencyCode

Currency of the transaction

eventCode

Operation (fix value)

eventStatusLabel

Message associated to relatedMsgStatus

metaData

Provision of the json as provided via API by the Marketplace.

Not present if field not provided as input.

operationDate

Date of the operation

operationSide

Direction of funds

1: pay in (a recharge is a payin)
0: transfer
-1: payout

operationStatus

Status of the transaction

R: registered
W: in the process of being cashed out
E: cashed
C: cancelled
S: suspended

operationType

Type of payment

1: Purchase
2: Refunds
4: Transfer
5: SCT/SDD fund receipt
6: Reload request or payout Identifiable via operationSide
7: Authorisation only
8: Pre-authorisation only
9: Unpaid

orderRef

The orderReference sent by the Marketplace for this payment

paymentMethodTypeId

Payment methodId

1: SDD
2: SCT
3: Transfer
4: Card
5: SWIFT
6: SDD B2B
10: SCT Inst (Instant Payment)
11: Payment Initiation

relatedMsgStatus

Additional complementary information provided to the status operation.

In addition to a C status:

0: customer initiates the cancellation (or usecase of SDD: Cancellation of direct debit following receipt of an unpaid amount before clearing)
200: transactions not completed by the client and canceled due to timeout
201: transactions declined during acceptation process

transactionId

TransactionId for this payment

versionNumber

Operation Version 2.0

Here is a "Body-Request" example you can receive after a card payment with operation version 2.0:

JSON

Copy

Copied

{
   "amount":"30.00",
   "currencyCode":"EUR",
   "eventCode":"operation",
   "eventStatusLabel":"None",
   "metaData":
    {
     "metadata":" "
    },
   "operationDate":"20240813",
   "operationSide":"1",
   "operationStatus":"R",
   "operationType":"1",
   "orderRef":"Spadaro-2024-08-13 11:15:27",
   "paymentMethodTypeId":"4",
   "relatedMsgStatus":"0",
   "transactionId":"7726422",
   "versionNumber":"2.0"
 }

Copy

Copied

Operation V3 is a more complete version of operation V2, it contains more financial information such as "Scheme fees" and "Commission Fees".

As the webhook "Operation V2", this event is sent by AgorayPay for any operation creation or change of status. Please refer to the payin operation life cycle discussion of the financial section to see all the statuses that will trigger an update notification.

The event includes the following parameters:

Field name

Description

amount

Amount of the operation

authNumber

Authorization number

commissionAmount

Comission amount taken by the marketplace

contractRef

Contract reference VAD/VADS

currencyCode

Currency of the transaction

eventCode

Operation (fix value)

eventStatusLabel

Message associated to relatedMsgStatus

exchangeFees

Exchange fees

maskedPAN

Masked PAN

metaData

Provision of the json as provided via API by the Marketplace.

Not present if field not provided as input.

operationDate

Date of the operation

operationSide

Direction of funds

1: pay in (a recharge is a payin)
0: transfer
-1: payout

operationStatus

Status of the transaction

R: registered
W: in the process of being cashed out
E: cashed
C: cancelled
S: suspended

operationType

Type of payment

1: Purchase
2: Refunds
4: Transfer
5: SCT/SDD fund receipt
6: Reload request or payout Identifiable via operationSide
7: Authorisation only
8: Pre-authorisation only
9: Unpaid

orderRef

The orderReference sent by the Marketplace for this payment

paymentFees

Payment fees

paymentMethodTypeId

Payment methodId

1: SDD
2: SCT
3: Transfer
4: Card
5: SWIFT
6: SDD B2B
10: SCT Inst (Instant Payment)
11: Payment Initiation

relatedMsgStatus

Additional complementary information provided to the status operation.

In addition to a C status:

0: customer initiates the cancellation (or usecase of SDD: Cancellation of direct debit following receipt of an unpaid amount before clearing)
200: transactions not completed by the client and canceled due to timeout
201: transactions declined during acceptation process

schemeFees

Scheme fees

transRefNo

Reference number of the transaction

transactionId

TransactionId for this payment

versionNumber

Operation Version 3.0

Here is a "Body-Request" example you can receive after a card payment with operation version 3.0:

JSON

Copy

Copied

{
   "amount":"5.00",
   "authNumber":"462242",
   "commissionAmount":"0.05",
   "contractRef":"2102019",
   "currencyCode":"EUR",
   "eventCode":"operation",
   "eventStatusLabel":"None",
   "exchangeFees":"0.00",
   "maskedPAN":"**************91",
   "metaData":
     {
       "metadata":" "
     },
   "operationDate":"20240731",
   "operationSide":"1",
   "operationStatus":"R",
   "operationType":"1",
   "orderRef":"Spadaro-2024-07-31 11:43:34",
   "paymentFees":"0.00",
   "paymentMethodTypeId":"4",
   "relatedMsgStatus":"0",
   "schemeFees":"0.00",
   "transRefNo":"38125957",
   "transactionId":"7562722",
   "versionNumber":"3.0"
}

Copy

Copied

This webhook, if activated on your contract, allows you to retrieve a paymentmethod in order to retrieve a customer IBAN attached to the paymentmethod.

After the payment initiation process ends with webhook E (when "E" is sent) , AgoraPay sends the Payment Method Alias to obtain the IBAN webhook.

This contains the “paymentMethodAlias” data that must be used as an input parameter for the GetIBAN API to receive the customer’s IBAN in plain text in return from the API.

This webhook is only sent after the E, not after the R or W, except for approval for testing but it therefore does not contain PM.

The event includes the following parameters:

Field name

Description

amount

Amount of the operation

currencyCode

Currency of the transaction

eventCode

Operation (fix value)

orderRef

The orderReference sent by the Marketplace for this payment

paymentMethodAlias

Data that must be used as an input parameter for the GetIBAN API

transactionId

TransactionId for this payment

versionNumber

Version 1.0

Here is a "Body-Request" example you can receive with this event:

JSON

Copy

Copied

{
   "amount":"1.00",
   "currencyCode":"EUR",
   "eventCode":"Effective_Payment_Method_Alias_IBAN",
   "orderRef":"order-123-1",
   "paymentMethodAlias":"PM202401290VINM1100",
   "transactionId":"47167921",
   "versionNumber":"1.0"
}

Copy

Copied

This webhook is linked to the SDD B2B and B2C direct debit payment method.

When the generation of the mandate is not associated with a payment (use of the Mandate API), a new type of “mandate” webhook is sent.

It is triggered each time the 'validity' state of the mandate changes, whether it was created during a payment or alone, whether it is a certified or signed mandate.

The event includes the following parameters:

Field name

Description

With RUM

Without RUM

eventCode

Operation (fix value)

yes

payerRef

Payer reference

yes

reference

Single reference of the Mandate

yes

no

sequence

Mandate status (OOFF/FRST/RCUR/FNAL)

yes

signatureFlag

Signature Indicator (true / false)

yes

status

1 – Pending

2 – Signed/Certified

yes

statusDescription

Status description

yes

useDate

If signature flag true and signature effective

yes

validity

True/False

yes (true)

yes (false)

versionNumber

Version 1.0

yes

Here is a "Body-Request" example you can receive with the event mandate (With RUM):

JSON

Copy

Copied

{
   "eventCode":"Mandate",
   "payerRef":"Payer_202401261001260058",
   "reference":"202401260907120VF121102",
   "sequence":"RCUR",
   "signatureFlag":"false",
   "status":"2",
   "statusDescription":"certified",
   "useDate":"20240126",
   "validity":"true",
   "versionNumber":"1.0"
}

Copy

Copied

Here is a "Body-Request" example you can receive with the event mandate (Without RUM):

JSON

Copy

Copied

{
   "eventCode":"Mandate",
   "payerRef":"Payer_202401301754240290",
   "sequence":"RCUR",
   "signatureFlag":"false",
   "status":"2",
   "statusDescription":"certified",
   "useDate":"20240130",
   "validity":"false",
   "versionNumber":"1.0"
}

Copy

Copied

This event is sent for an unpaid transaction.

For more info. , contact the implementation manager.

The event includes the following parameters:

Field name

Description

amount

Amount of the operation

currencyCode

Currency of the transaction

eventCode

Operation (fix value)

eventStatusLabel

Message associated to relatedMsgStatus

operationDate

Date of the operation

operationMasterId

Master id of the operation

operationSide

Direction of funds

1: pay in (a recharge is a payin)
0: transfer
-1: payout

operationStatus

Status of the transaction

R: registered
W: in the process of being cashed out
E: cashed
C: cancelled
S: suspended

operationType

Type of payment

1: Purchase
2: Refunds
4: Transfer
5: SCT/SDD fund receipt
6: Reload request or payout Identifiable via operationSide
7: Authorisation only
8: Pre-authorisation only
9: Unpaid

orderRef

The orderReference sent by the Marketplace for this payment

paymentMethodTypeId

Payment methodId

1: SDD
2: SCT
3: Transfer
4: Card
5: SWIFT
6: SDD B2B
10: SCT Inst (Instant Payment)
11: Payment Initiation

rejectReasonCode

Reject reason code

rejectReasonLabel

Reject reason label

relatedMsgStatus

Additional complementary information provided to the status operation.

In addition to a C status:

0: customer initiates the cancellation (or usecase of SDD: Cancellation of direct debit following receipt of an unpaid amount before clearing)
200: transactions not completed by the client and canceled due to timeout
201: transactions declined during acceptation process

transactionId

TransactionId for this payment

versionNumber

Version 2.0

Here is a "Body-Request" example you can receive with the event "Unpaid"

JSON

Copy

Copied

{
"amount":"3.10",
"currencyCode":"EUR",
"eventCode":"Unpaid",
"eventStatusLabel":"None",
"operationDate":"20240725",
"operationMasterId":"6253726",
"operationSide":"1",
"operationStatus":"E",
"operationType":"9",
"orderRef":"OrderReference",
"paymentMethodTypeId":"2",
"rejectReasonCode":"AC01",
"rejectReasonLabel":"CreditorAgentorDebtorAgentoftheoriginaltransactionisnotallowed",
"relatedMsgStatus":"0",
"transactionId":"UNPAID-1562836",
"versionNumber":"2.0"
}

Copy

Copied

You are informed about the availability of a monthly report by this webhook, the report is available in PDF format on your agorapay portal.

The event includes the following parameters:

Field name

Description

accountNumber

Account number

docName

Name of the document

eventCode

Operation (fix value)

operationDate

Date of the operation

parentThirdPartyName

Parent third party name

reportName

Name of the report

reportingMonth

Month of the report

reportingYear

Year of the report

thirdPartyName

Third party name

thirdPartyRef

Third party reference

type

Type

versionNumber

Version 1.0

Here is a "Body-Request" example you can receive with the event "Report" :

JSON

Copy

Copied

{
"accountNumber":"1737800001EUR145367331",
"docName":"Monthly_report",
"eventCode":"Report",
"operationDate":"20240801",
"parentThirdPartyName":"ParentThirdPartyName",
"reportName":"STATEMENT",
"reportingMonth":"7",
"reportingYear":"2024",
"thirdPartyName":"ThirdPartyName Marchand 1",
"thirdPartyRef":"ThirdPartyRef",
"type":"2",
"versionNumber":"1.0"
}

Copy

Copied

This webhook can be enabled if you use the paymentIframe API.

In the event that the customer does not follow through with the payment and/or stops during the payment process before entering their bank card information. (abandonment or closure of the iframe), this event allows you to be notified approximately 1 hour after that the payment has been abandoned.

Once you receive this webhook you can consider the payment as abandoned.

The event includes the following parameters:

Field name

Description

amount

Amount of the operation

currencyCode

Currency of the transaction

eventCode

Operation (fix value)

orderId

Id of the order

orderRef

The orderReference sent by the Marketplace for this payment

orderStatusCode

order status code

versionNumber

Version 2.0

Here is a "Body-Request" example you can receive with the event "Abandoned shopping cart" :

JSON

Copy

Copied

{
"amount":"10.00",
"currencyCode":"EUR",
"eventCode":"Abandoned_shopping_cart",
"orderId":"53071234",
"orderRef":"1234aaba9df6d1f1",
"orderStatusCode":"20",
"versionNumber":"2.0"
}

Copy

Copied

The progress of your merchant enrollment request is communicated to you via this webhook when you use the enrollment API or when the merchant validates the SelfCare enrollment phase.

Each time the status of the enrollment request changes, you receive a webhook.

the “pending” state has a webhook that contains the "SellerAccountnumber" (AgoraPay technical account number for that merchant) and the paymentmethod alias (useful if you perform the PayOut via API). These two pieces of information can also be found in the API feedback and the status update webhook mentioned earlier.

The event includes the following parameters:

Field name

Description

accountNumber

Account number

eventCode

Operation (fix value)

paymentMethodAlias

Payment method alias

requestId

Request id

requestStatus

The list of requestStatus codes present in the webhook:

0: "Created" ; The request is being initialized
9: "Pending" ; The request is initialized but requires some documents
2: "Validated" ; The request has been validated by the BO
3: "Rejected" ; The request has been rejected by the BO
5: "Canceled" ; The request has been canceled by the client
6: "Expired" ; The request has been expired
11: "To check" ; The documents must be checked by the BO

thirdPartyName

Third party name

thirdPartyRef

Third party reference

updateUDateTime

UpdateU date/time

versionNumber

Version 1.0

Here is a "Body-Request" example you can receive with the event "Account holder registration" :

JSON

Copy

Copied

{
"accountNumber":"1737800001EUR17456811",
"eventCode":"Account_Holder_Registration",
"paymentMethodAlias":"PM1998190DEYS110024",
"requestId":"CAPS109028401HEUY2",
"requestStatus":"9",
"thirdPartyName":"ThirdPartyName",
"thirdPartyRef":"CAPS6363636",
"updateUDateTime":"20240819134117761",
"versionNumber":"1.0"
}

Copy

Copied

Webhook events Copy section link Copied!

Types of Events Copy section link Copied!

Operation V2 Copy section link Copied!

Operation V3 Copy section link Copied!

Payment Method Alias to get IBAN Copy section link Copied!

Mandate Copy section link Copied!

Unpaid Copy section link Copied!

Report Copy section link Copied!

Abandoned Shopping Cart Copy section link Copied!

Account Holder Registration Copy section link Copied!