The Hook object
Once setup, hook notifications allow us to make a request to a specific URL on your server to make you aware of various Events (such as a failed PayOut). You can set up one URL for each EventType. Here are the rules:
- After 100 failed notifications for an
EventType(we couldn’t reach your URL), the hook will be automatically setValidityto "INVALID" andStatusto "DISABLED". - Every 10 failed notifications you will receive an email warning you of the issue.
- Each time you have a successful notification, we reset this counter (so if you have 99 failures, then 1 successful and then 1 failure, this won’t result in the 100 failed email alert).
- Changing the URL for a hook will not reset your failure count though.
- The URL that we hook must respond with a 200 status code within 2 seconds – otherwise we will consider the hook a failure
- You are strongly advised to do a GET on the resource to check its Status (to ensure the Event is still relevant, but also to ensure the hook is authentic).
- You can also view and manage your Hook notifications from the MANGOPAY Dashboard. You have the possibility to test the hook to see if it is working well. Note that when setting up a new hook, then when saving it a test is launch automatically.
- You must use a trusted SSL certificate - self-signed certificates are not supported.
Note that we have released a new functionality Retry on hooks. For any failed hook (no response 200), we now resend the notification every ten minutes during the first hour and every eight hours for three days. With this feature, you receive either one notification, or more for the same event. Therefore, we advise you to make your event processing idempotent to avoid duplicated event receipts.
Notification format: ...your-site.com?EventType=EventType&RessourceId=RessourceId&Date=Timestamp
Where the RessourceId is the Id of the object in question.
Note that in the URL parameters, RessourceId has two "s", and not one as in the API objects - this is a mistake and will be corrected in a future API version
Example: If you want to create a notification for the event type "KYC_SUCCEEDED" on your URL: "http://www.mynotificationurl.com" you will receive this ping: http://www.mynotificationurl.com?EventType=KYC_SUCCEEDED&RessourceId=1309853&Date=1397037093
A useful cloud tool for testing notifications in sandbox is requestbin.com
The following EventType are available:
| Name | RessourceId | Description |
|---|---|---|
| COUNTRY_AUTHORIZATION_UPDATED | CountryCode | An authorisation related to a country has been modified. |
| DEPOSIT_PREAUTHORIZATION_CREATED | DepositId | The Deposit PreAuthorization object has been successfully created. |
| DEPOSIT_PREAUTHORIZATION_FAILED | DepositId | The authorization upon this DepositId has failed. |
| DEPOSIT_PREAUTHORIZATION_PAYMENT_WAITING | DepositId | The authorization upon this DepositId has been successful. It can now be debited. |
| DEPOSIT_PREAUTHORIZATION_PAYMENT_EXPIRED | DepositId | The authorization upon this DepositId has expired. |
| DEPOSIT_PREAUTHORIZATION_PAYMENT_CANCEL_REQUESTED | DepositId | The cancel request upon this authorization has been taken into account. |
| DEPOSIT_PREAUTHORIZATION_PAYMENT_CANCELED | DepositId | The authorization upon this DepositId has been canceled. |
| DEPOSIT_PREAUTHORIZATION_PAYMENT_VALIDATED | DepositId | The authorization upon this DepositId has been successfully debited. |
| DISPUTE_ACTION_REQUIRED | DisputeId | When a contestable dispute is created, we notify the platform that an action is expected on its side in a short period of time. |
| DISPUTE_CLOSED | DisputeId | A dispute has been closed. It can either be a WIN or a LOOSE for the platform. |
| DISPUTE_CREATED | DisputeId | A dispute has been created. It can either be closed directly or need review from the platform. |
| DISPUTE_DOCUMENT_CREATED | DisputeDocumentId | A document has been added to the dispute. Either by internal or external source. |
| DISPUTE_DOCUMENT_VALIDATION_ASKED | DisputeDocumentId | A document has been added to the dispute and needs to be validated by our analysts. |
| DISPUTE_DOCUMENT_SUCCEEDED | DisputeDocumentId | The document has been validated by our internal teams. |
| DISPUTE_DOCUMENT_FAILED | DisputeDocumentId | The document has been refused. |
| DISPUTE_FURTHER_ACTION_REQUIRED | DisputeId | To settle the dispute, additional documents are required. |
| DISPUTE_SENT_TO_BANK | DisputeId | Once the documents have been validated, we have sent them to the bank for review and approval. |
| DISPUTE_SUBMITTED | DisputeId | The platform decided to contest the dispute either entirely or partially. |
| INSTANT_PAYOUT_SUCCEEDED | PayOutId | The Instant Payout request has succeeded. |
| INSTANT_PAYOUT_FALLBACKED | PayOutId | The Payout could not be processed instantly but it has been fallbacked (48 hours to process). |
| INSTANT_PAYOUT_FAILED | PayOutId | The Instant Payout request has failed. |
| KYC_CREATED | KYCDocumentId | The KYC document has been created. |
| KYC_SUCCEEDED | KYCDocumentId | The KYC document has been validated by our compliance team. |
| KYC_FAILED | KYCDocumentId | The KYC document has been refused by our compliance team. |
| KYC_VALIDATION_ASKED | KYCDocumentId | The KYC document has been submitted for validation and it is being processed. |
| KYC_OUTDATED | KYCDocumentId | The KYC document is not valid anymore. This is due to an amendment of user’s identity. |
| MANDATE_CREATED | MandateId | The mandate request has been submitted for creation. |
| MANDATE_FAILED | MandateId | The mandate request has failed. |
| MANDATE_ACTIVATED | MandateId | The mandate request has been successfully created and validated. A bankwire can be initiated. |
| MANDATE_SUBMITTED | MandateId | The mandate request has been successfully validated, an email has been sent to the end-user (if email configured). |
| MANDATE_EXPIRED | MandateId | The mandate has expired. Bankwire cannot be initiated anymore. |
| PAYIN_NORMAL_CREATED | PayinId | A PayIn request has been created. |
| PAYIN_NORMAL_SUCCEEDED | PayinId | A PayIn request has been successfully processed. |
| PAYIN_NORMAL_FAILED | PayinId | A PayIn request has failed. |
| PAYIN_REFUND_CREATED | RefundId | A Refund request upon a PayinId has been created. |
| PAYIN_REFUND_SUCCEEDED | RefundId | A Refund request upon a PayinId has been processed successfully. |
| PAYIN_REFUND_FAILED | RefundId | A Refund request upon a PayinId has failed. |
| PAYIN_REPUDIATION_CREATED | RepudiationId | A chargeback has been filed and has been created in MANGOPAY's ecosystem (Repudiation Wallet). |
| PAYIN_REPUDIATION_SUCCEEDED | RepudiationId | A chargeback has been filed and successfully sent back to the PayIn owner. |
| PAYIN_REPUDIATION_FAILED | RepudiationId | A chargeback has been filed but the movement from the repudiation wallet back to the PayIn owner has failed. |
| PAYOUT_NORMAL_CREATED | PayOutId | A Payout request has been created. |
| PAYOUT_NORMAL_SUCCEEDED | PayOutId | A Payout request has succeeded. |
| PAYOUT_NORMAL_FAILED | PayOutId | A Payout request has failed. |
| PAYOUT_REFUND_CREATED | PayOutId | A Payout Refund request has been created. |
| PAYOUT_REFUND_SUCCEEDED | PayOutId | A Payout Refund request has succeeded. |
| PAYOUT_REFUND_FAILED | PayOutId | A Payout Refund request has failed. |
| PREAUTHORIZATION_CREATED | PreAuthorizationId | The PreAuthorization object has been successfully created. |
| PREAUTHORIZATION_SUCCEEDED | PreAuthorizationId | The authorization upon this PreAuthorizationId has been successful. |
| PREAUTHORIZATION_FAILED | PreAuthorizationId | The authorization upon this PreAuthorizationId has failed. |
| PREAUTHORIZATION_PAYMENT_WAITING | PreAuthorizationId | The PreAuthorization object can now be debited. |
| PREAUTHORIZATION_PAYMENT_EXPIRED | PreAuthorizationId | The authorization upon this PreAuthorizationId has expired. |
| PREAUTHORIZATION_PAYMENT_CANCELED | PreAuthorizationId | The authorization upon this PreAuthorizationId has been canceled. |
| PREAUTHORIZATION_PAYMENT_VALIDATED | PreAuthorizationId | The authorization upon this PreAuthorizationId has been successfully debited. |
| RECURRING_REGISTRATION_CREATED | RecurringRegistrationId | The recurring object has been successfully created. |
| RECURRING_REGISTRATION_AUTH_NEEDED | RecurringRegistrationId | A payin upon this recurring object requires an authentication. |
| RECURRING_REGISTRATION_IN_PROGRESS | RecurringRegistrationId | The recurring object is in a valid state. Payins upon this recurring object are possible. |
| RECURRING_REGISTRATION_ENDED | RecurringRegistrationId | The recurring object has been ended. Please, initiate a new recurrence. |
| TRANSFER_NORMAL_CREATED | TransferId | The transfer has been attempted. |
| TRANSFER_NORMAL_SUCCEEDED | TransferId | The transfer has been successfully processed. |
| TRANSFER_NORMAL_FAILED | TransferId | The transfer could not be processed. |
| TRANSFER_REFUND_CREATED | RefundId | The transaction refund has been attempted. |
| TRANSFER_REFUND_SUCCEEDED | RefundId | The transaction refund has been successfully processed. |
| TRANSFER_REFUND_FAILED | RefundId | The transaction refund could not be processed. |
| TRANSFER_SETTLEMENT_CREATED | SettlementId | The settlement transaction has been attempted. |
| TRANSFER_SETTLEMENT_SUCCEEDED | SettlementId | The settlement transaction has been successfully processed. |
| TRANSFER_SETTLEMENT_FAILED | SettlementId | The settlement transaction could not be processed. |
| UBO_DECLARATION_CREATED | UboDeclarationId | The UBODeclaration has been created. |
| UBO_DECLARATION_VALIDATION_ASKED | UboDeclarationId | The UBODeclaration has been submitted for validation and it is being processed. |
| UBO_DECLARATION_REFUSED | UboDeclarationId | The UBODeclaration validation failed. It was refused by our Compliance team. |
| UBO_DECLARATION_VALIDATED | UboDeclarationId | The UBODeclaration has been validated by our compliance team |
| UBO_DECLARATION_INCOMPLETE | UboDeclarationId | The submitted UBODeclaration is incomplete and additional information may be required. |
| USER_INFLOWS_BLOCKED | UserId | The user cashin has been blocked by MANGOPAY. |
| USER_INFLOWS_UNBLOCKED | UserID | The user cashin has been unblocked by MANGOPAY. |
| USER_KYC_REGULAR | UserId | The user has been KYC validated by our compliance team. |
| USER_KYC_LIGHT | UserId | The User is not authenticated on our side and is, hence, subject to Anti-Money Laundering limits. |
| USER_OUTFLOWS_BLOCKED | UserId | The user cashout has been blocked by MANGOPAY. |
| USER_OUTFLOWS_UNBLOCKED | UserId | The user cashout has been unblocked by MANGOPAY. |
Parameters
Urlstring:
Maximum length is 255 characters
This is the URL where your receive notification for each EventType
StatusHookStatus:
DISABLED, ENABLED
The status of the hook
Whether the hook is enabled or not
ValidityHookValidity:
VALID, INVALID
The validity of a Hook URL
Whether the hook is valid or not
EventTypeEventType:
PAYIN_NORMAL_CREATED, PAYIN_NORMAL_SUCCEEDED, PAYIN_NORMAL_FAILED, PAYOUT_NORMAL_CREATED, PAYOUT_NORMAL_SUCCEEDED, PAYOUT_NORMAL_FAILED, INSTANT_PAYOUT_SUCCEEDED, INSTANT_PAYOUT_FALLBACKED, INSTANT_PAYOUT_FAILED, TRANSFER_NORMAL_CREATED, TRANSFER_NORMAL_SUCCEEDED, TRANSFER_NORMAL_FAILED, PAYIN_REFUND_CREATED, PAYIN_REFUND_SUCCEEDED, PAYIN_REFUND_FAILED, PAYOUT_REFUND_CREATED, PAYOUT_REFUND_SUCCEEDED, PAYOUT_REFUND_FAILED, TRANSFER_REFUND_CREATED, TRANSFER_REFUND_SUCCEEDED, TRANSFER_REFUND_FAILED, KYC_CREATED, KYC_VALIDATION_ASKED, KYC_SUCCEEDED, KYC_FAILED, KYC_OUTDATED, PAYIN_REPUDIATION_CREATED, PAYIN_REPUDIATION_SUCCEEDED, PAYIN_REPUDIATION_FAILED, DISPUTE_DOCUMENT_CREATED, DISPUTE_DOCUMENT_VALIDATION_ASKED, DISPUTE_DOCUMENT_SUCCEEDED, DISPUTE_DOCUMENT_FAILED, DISPUTE_CREATED, DISPUTE_SUBMITTED, DISPUTE_ACTION_REQUIRED, DISPUTE_FURTHER_ACTION_REQUIRED, DISPUTE_CLOSED, DISPUTE_SENT_TO_BANK, TRANSFER_SETTLEMENT_CREATED, TRANSFER_SETTLEMENT_SUCCEEDED, TRANSFER_SETTLEMENT_FAILED, MANDATE_CREATED, MANDATE_FAILED, MANDATE_ACTIVATED, MANDATE_SUBMITTED, MANDATE_EXPIRED, PREAUTHORIZATION_CREATED, PREAUTHORIZATION_FAILED, PREAUTHORIZATION_SUCCEEDED, PREAUTHORIZATION_PAYMENT_WAITING, PREAUTHORIZATION_PAYMENT_EXPIRED, PREAUTHORIZATION_PAYMENT_CANCELED, PREAUTHORIZATION_PAYMENT_VALIDATED, UBO_DECLARATION_CREATED, UBO_DECLARATION_VALIDATION_ASKED, UBO_DECLARATION_REFUSED, UBO_DECLARATION_VALIDATED, UBO_DECLARATION_INCOMPLETE, USER_KYC_REGULAR, USER_KYC_LIGHT, USER_INFLOWS_BLOCKED, USER_INFLOWS_UNBLOCKED, USER_OUTFLOWS_BLOCKED, USER_OUTFLOWS_UNBLOCKED
A type of event
The event type
Tagstring:
Maximum length is 255 characters
Custom data that you can add to this item
CreationDatetimestamp
When the item was created