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
DISPUTE_CLOSED
DISPUTE_CREATED
DISPUTE_DOCUMENT_CREATED
DISPUTE_DOCUMENT_VALIDATION_ASKED
DISPUTE_DOCUMENT_SUCCEEDED
DISPUTE_DOCUMENT_FAILED
DISPUTE_FURTHER_ACTION_REQUIRED
DISPUTE_SENT_TO_BANK
DISPUTE_SUBMITTED
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 RessourceId The KYC document is not valid anymore. This is due to an amendment of user’s identity.
MANDATE_CREATED
MANDATE_FAILED
MANDATE_ACTIVATED
MANDATE_SUBMITTED
MANDATE_EXPIRED
PAYIN_NORMAL_CREATED
PAYIN_NORMAL_SUCCEEDED
PAYIN_NORMAL_FAILED
PAYIN_REFUND_CREATED
PAYIN_REFUND_SUCCEEDED
PAYIN_REFUND_FAILED
PAYIN_REPUDIATION_CREATED
PAYIN_REPUDIATION_SUCCEEDED
PAYIN_REPUDIATION_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
PREAUTHORIZATION_SUCCEEDED
PREAUTHORIZATION_FAILED
PREAUTHORIZATION_PAYMENT_WAITING
PREAUTHORIZATION_PAYMENT_EXPIRED
PREAUTHORIZATION_PAYMENT_CANCELED
PREAUTHORIZATION_PAYMENT_VALIDATED
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
TRANSFER_NORMAL_SUCCEEDED
TRANSFER_NORMAL_FAILED
TRANSFER_REFUND_CREATED
TRANSFER_REFUND_SUCCEEDED
TRANSFER_REFUND_FAILED
TRANSFER_SETTLEMENT_CREATED
TRANSFER_SETTLEMENT_SUCCEEDED
TRANSFER_SETTLEMENT_FAILED
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:

UNKNOWN, 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, 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

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

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, 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

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

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

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

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