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 to Validity="INVALID" and Status= "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
  • We are currently unable to send hooks to servers that accept only TLS 1.2 (in sandbox this is possible, but not in production) - we will improve this in the future, but we do not yet have a date confirmed
  • You must use a trusted SSL certificate - self-signed certificates are not supported

The following EventType are available :

  • 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
  • PAYIN_REPUDIATION_CREATED, PAYIN_REPUDIATION_SUCCEEDED, PAYIN_REPUDIATION_FAILED
  • KYC_CREATED, KYC_SUCCEEDED, KYC_FAILED, KYC_VALIDATION_ASKED
  • 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
  • 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

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 recieve this ping: http://www.mynotificationurl.com?EventType=KYC_SUCCEEDED&RessourceId=1309853&Date=1397037093

A useful cloud tool for testing notifications in sandbox is requestb.in.

Parameters

Id
string

string:

Maximum length is 255 characters

The item's ID

CreationDate
timestamp

timestamp

When the item was created

Tag
string

string:

Maximum length is 255 characters

Custom data that you can add to this item

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

A type of event

The event type

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"Url": "http://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

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

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

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 :
{
"Tag": "custom meta",
"EventType": "PAYIN_NORMAL_CREATED",
"Url": "http://www.my-site.com/hooks/"
}
require_once("mangopay.php");

try {


$Hook = new \MangoPay\Hook();
$Hook->Tag = "custom meta";
$Hook->EventType = "PAYIN_NORMAL_CREATED";
$Hook->Url = "http://www.my-site.com/hooks/";

$Result = $Api->Hooks->Create($Hook);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
POST .../hooks/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"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
require_once("mangopay.php");

try {

$HookId = 12639364;

$Hook = $Api->Hooks->Get($HookId);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
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

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

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 :
{
"Tag": "custom meta",
"Status": "ENABLED",
"Url": "http://www.my-site.com/hooks/"
}
require_once("mangopay.php");

try {

$Hook = new \MangoPay\Hook();
$Hook->Tag = "custom meta";
$Hook->Status = "ENABLED";
$Hook->Url = "http://www.my-site.com/hooks/";
$Hook->Id = 12639364;

$Result = $Api->Hooks->Update($Hook);

} catch(MangoPay\Libraries\ResponseException $e) {
// handle/log the response exception with code $e->GetCode(), message $e->GetMessage() and error(s) $e->GetErrorDetails()

} catch(MangoPay\Libraries\Exception $e) {
// handle/log the exception $e->GetMessage()

}
PUT .../hooks// HTTP/1.1
Body Parameters :
{
"Tag": "",
"Status": "",
"Url": ""
}

List all Hooks

GET .../v2.01/ClientId

The ID of your client account

/hooks/

Get parameters

Page
int

int

optional

The page number of results you wish to return

Per_Page
int

int

optional

The number of results to return per page

Sort
ColumnAndDirection

ColumnAndDirection:

The column to sort against and direction, separated by a :

optional

The column to sort against and direction - only CreationDate (or Date for the events) is available and ASC or DESC for the direction

  • View
  • Code
    A code sample is not available
  • Run
  • View
  • Code
    A code sample is not available
  • Run
GET .../hooks/ HTTP/1.1
Get Parameters :
{
"Page": 1,
"Per_Page": 25,
"Sort": "CreationDate:DESC"
}
GET .../hooks/ HTTP/1.1
Get Parameters :
{
"Page": ,
"Per_Page": ,
"Sort": ""
}