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 new 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
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 is a success.
INSTANT_PAYOUT_FALLBACKED PayOutId The Payout could not be process instantly but it has been fallbacked (48 hours to process).
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 validation failed. It is either due to a technical error or it was 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. It is most likely 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
PAYOUT_NORMAL_SUCCEEDED
PAYOUT_NORMAL_FAILED
PAYOUT_REFUND_CREATED
PAYOUT_REFUND_SUCCEEDED
PAYOUT_REFUND_FAILED
PREAUTHORIZATION_CREATED
PREAUTHORIZATION_SUCCEEDED
PREAUTHORIZATION_FAILED
PREAUTHORIZATION_PAYMENT_WAITING
PREAUTHORIZATION_PAYMENT_EXPIRED
PREAUTHORIZATION_PAYMENT_CANCELED
PREAUTHORIZATION_PAYMENT_VALIDATED
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
USER_INFLOWS_UNBLOCKED
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
USER_OUTFLOWS_UNBLOCKED

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