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 set Validity to "INVALID" and Status to "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.
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

Url
string

string:

Maximum length is 255 characters

This is the URL where your receive notification for each EventType

Status
HookStatus

HookStatus:

DISABLED, ENABLED

The status of the hook

Whether the hook is enabled or not

Validity
HookValidity

HookValidity:

VALID, INVALID

The validity of a Hook URL

Whether the hook is valid or not

EventType
EventType

EventType:

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

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

CreationDate
timestamp

timestamp

When the item was created

{
"Url": "https://www.my-site.com/hooks/",
"Status": "ENABLED",
"Validity": "VALID",
"EventType": "PAYIN_NORMAL_CREATED",
"Tag": "custom meta",
"CreationDate": 12926321
}

Create a Hook

You can only create one Hook for each EventType

POST .../v2.01/ClientId

The ID of your client account

/hooks/

Parameters

EventType
EventType

EventType:

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

required

The event type

Url
string

string:

Maximum length is 255 characters

required

This is the URL where your receive notification for each EventType

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../hooks/ HTTP/1.1
Body Parameters :
{
"EventType": "PAYIN_NORMAL_CREATED",
"Url": "http://www.my-site.com/hooks/",
"Tag": "custom meta"
}
POST .../hooks/ HTTP/1.1
Body Parameters :
{
"EventType": "",
"Url": "",
"Tag": ""
}

View a Hook

GET .../v2.01/ClientId

The ID of your client account

/hooks/HookId

The ID of a Hook

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../hooks/:HookId/ HTTP/1.1
GET .../hooks// HTTP/1.1

Update a Hook

PUT .../v2.01/ClientId

The ID of your client account

/hooks/HookId

The ID of a Hook

/

Parameters

Status
HookStatus

HookStatus:

DISABLED, ENABLED

The status of the hook

optional

Whether the hook is enabled or not

Url
string

string:

Maximum length is 255 characters

optional

This is the URL where your receive notification for each EventType

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

  • View
  • Code
  • Run
  • View
  • Code
  • Run
PUT .../hooks/:HookId/ HTTP/1.1
Body Parameters :
{
"Status": "ENABLED",
"Url": "http://www.my-site.com/hooks/",
"Tag": "custom meta"
}
PUT .../hooks// HTTP/1.1
Body Parameters :
{
"Status": "",
"Url": "",
"Tag": ""
}

List all Hooks

GET .../v2.01/ClientId

The ID of your client account

/hooks/
  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../hooks/ HTTP/1.1
GET .../hooks/ HTTP/1.1
Share feedback
Live chat
No agent is free at the moment please send us a request through our contact form