The Refund object

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

DebitedFunds
Money

Money:

View Sub-parameters

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

CreditedFunds
Money

Money:

View Sub-parameters

Details about the funds that are being credited (DebitedFunds – Fees = CreditedFunds)

CreditedFunds.Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

The currency - should be ISO_4217 format

CreditedFunds.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Fees
Money

Money:

View Sub-parameters

Information about the fees that were taken by the client for this transaction (and were hence transferred to the Client's platform wallet)

Fees.Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

The currency - should be ISO_4217 format

Fees.Amount
int

int

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

DebitedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet that was debited

CreditedWalletId
string

string:

Maximum length is 255 characters

The ID of the wallet where money will be credited

AuthorId
string

string:

Maximum length is 255 characters

A user's ID

CreditedUserId
string

string:

Maximum length is 255 characters

The user ID who is credited (defaults to the owner of the wallet)

Nature
TransactionNature

TransactionNature:

REGULAR, REPUDIATION, REFUND, SETTLEMENT

The nature of the transaction

Status
TransactionStatus

TransactionStatus:

CREATED, SUCCEEDED, FAILED

The status of the transaction

ExecutionDate
timestamp

timestamp

When the transaction happened

ResultCode
string

string:

Maximum length is 255 characters

The result code

ResultMessage
string

string:

Maximum length is 255 characters

A verbal explanation of the ResultCode

Type
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The type of the transaction

InitialTransactionId
string

string:

Maximum length is 255 characters

The initial transaction ID

InitialTransactionType
TransactionType

TransactionType:

PAYIN, TRANSFER, PAYOUT

The initial transaction type

RefundReason
RefundReason

RefundReason:

More info about the reason for Refund

View Sub-parameters

Contains info about the reason for refund

RefundReason.RefusedReasonType
RefundReasonType

RefundReasonType:

INITIALIZED_BY_CLIENT, BANKACCOUNT_INCORRECT, OWNER_DOT_NOT_MATCH_BANKACCOUNT, BANKACCOUNT_HAS_BEEN_CLOSED, WITHDRAWAL_IMPOSSIBLE_ON_SAVINGS_ACCOUNTS, OTHER

The reason type for the refund

The type of reason for refusal

RefundReason.RefusedReasonMessage
string

string:

Maximum length is 255 characters

The message accompanying a refusal

{
"Id": "8494514",
"CreationDate": 12926321,
"Tag": "custom meta",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"CreditedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
},
"DebitedWalletId": "8519987",
"CreditedWalletId": "8494559",
"AuthorId": "8494514",
"CreditedUserId": "8494514",
"Nature": "REGULAR",
"Status": "SUCCEEDED",
"ExecutionDate": 1463496101,
"ResultCode": "000000",
"ResultMessage": "The transaction was successful",
"Type": "PAYIN",
"InitialTransactionId": "1463496101",
"InitialTransactionType": "PAYIN",
"RefundReason": {
"RefusedReasonType": "DOCUMENT_UNREADABLE",
"RefusedReasonMessage": "The document was not readable :-("
}
}

Create a PayIn Refund

A PayIn Refund is a request to reimburse a user on their payment card. The money which has already been paid will automatically go back to the user’s bank account.

  • Minimum amount to refund is 1€.
  • If you're doing a partial Refund, note that you can only refund the same amount on the same transaction once per day (this is to prevent unintended duplicate refunds). After 24h you can do another refund of the same amount on the same transaction. If it is a different amount on the same transaction, there is not this limit.

You can refund Card Direct Payins, Card Web Payins, Preauthorization Payins, Direct-Debit Web Payins and Direct-Debit Direct Payins. Note that for Direct-Debit Direct Payins, you are limited to 5 refunds for each Payin.

If you do not specify DebitedFunds and Fees parameters, it will automatically fully refund the PayIn. However if you do provide one or the other, you must provide both. Note that Fees must be negative if you wish to refund them - adding a positive value for the Fees is a way to charge your customers for the Refund (in the same way you might for a PayIn, Transfer or any other Transaction

POST .../v2.01/ClientId

The ID of your client account

/payins/PayInId

The Id of a PayIn

/refunds/

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

AuthorId
string

string:

Maximum length is 255 characters

required

A user's ID

DebitedFunds
Money

Money:

View Sub-parameters

optional

Information about the funds that are being debited

DebitedFunds.Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

required

The currency - should be ISO_4217 format

DebitedFunds.Amount
int

int

required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

Fees
Money

Money:

View Sub-parameters

optional

Information about the fees that were taken by the client for this transaction (and were hence transferred to the Client's platform wallet)

Fees.Currency
CurrencyIso

CurrencyIso:

EUR, GBP, PLN, CHF, NOK, SEK, DKK, USD (beta), CAD (beta), AUD (beta), XXX

ISO 4217 format

required

The currency - should be ISO_4217 format

Fees.Amount
int

int

required

An amount of money in the smallest sub-division of the currency, e.g. 12.60 EUR would be represented as 1260 whereas 12 JPY would be represented as just 12)

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../payins/:PayInId/refunds/ HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"AuthorId": "8494514",
"DebitedFunds": {
"Currency": "EUR",
"Amount": 12
},
"Fees": {
"Currency": "EUR",
"Amount": 12
}
}
require_once("mangopay.php");

try {

$PayInId = 12639078;

$Refund = new \MangoPay\Refund();
$Refund->Tag = "custom meta";
$Refund->AuthorId = "8494514";
$Refund->DebitedFunds = new \MangoPay\Money();
$Refund->DebitedFunds->Currency = "EUR";
$Refund->DebitedFunds->Amount = 12;
$Refund->Fees = new \MangoPay\Money();
$Refund->Fees->Currency = "EUR";
$Refund->Fees->Amount = 12;

$Result = $Api->PayIns->CreateRefund($PayInId, $Refund);

} 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 .../payins//refunds/ HTTP/1.1
Body Parameters :
{
"Tag": "",
"AuthorId": "",
"DebitedFunds": {
"Currency": "",
"Amount":
},
"Fees": {
"Currency": "",
"Amount":
}
}

Create a Transfer Refund

POST .../v2.01/ClientId

The ID of your client account

/transfers/TransferId

The ID of a transfer

/refunds

Parameters

Tag
string

string:

Maximum length is 255 characters

optional

Custom data that you can add to this item

AuthorId
string

string:

Maximum length is 255 characters

required

A user's ID

  • View
  • Code
  • Run
  • View
  • Code
  • Run
POST .../transfers/:TransferId/refunds HTTP/1.1
Body Parameters :
{
"Tag": "custom meta",
"AuthorId": "8494514"
}
require_once("mangopay.php");

try {

$TransferId = 12639390;

$Refund = new \MangoPay\Refund();
$Refund->Tag = "custom meta";
$Refund->AuthorId = "8494514";

$Result = $Api->Transfers->CreateRefund($TransferId, $Refund);

} 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 .../transfers//refunds HTTP/1.1
Body Parameters :
{
"Tag": "",
"AuthorId": ""
}

PayOut Refunds

A Payout Refund is a request only generated by Mangopay when the bank of the user rejected the transfer. In this case we reimburse the payout and so the funds into the wallet. So the payout object remains in "SUCCEEDED" but we create a refund object and you receive a "PAYOUT_REFUND_SUCCEEDED" notification and event.

Note that PayOut refunds can only be generated by MANGOPAY. The Id is obtained through the event or the hook notification

View a Refund

No matter if it is

  • a PayIn refund : request to reimburse a user on its payment card. The money which has already been paid will automatically go back to the user’s bank account
  • a Transfer : request to reimburse a wallet. The money which comes from a wallet and has already been transferred to another one goes back to the wallet it came from
  • or a PayOut refund

Note that PayOut refunds can only be generated by MANGOPAY. The Id is obtained through the event or the hook notification PAYOUT_REFUND_SUCCEEDED

GET .../v2.01/ClientId

The ID of your client account

/refunds/RefundId

The ID of a refund

/
  • View
  • Code
  • Run
  • View
  • Code
  • Run
GET .../refunds/:RefundId/ HTTP/1.1
require_once("mangopay.php");

try {

$RefundId = 12639385;

$Refund = $Api->Refunds->Get($RefundId);

} 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 .../refunds// HTTP/1.1