Update the Payment Method
Please note
This guide does not cover the basics of API authentication or the format of requests and responses. Please review these sections if you are unfamiliar with these concepts.
All of the code examples in our guides are written in PHP and are based on our HAPI Client, developed by SlimPay to reduce the code complexity of interfacing with our API. Please refer to our HTTP client page for more details on using these libraries.
After setting up a payment method, the subscriber (your customer) may want to:
- use a different method (switching from direct debit to card or vice versa)
- use the same method but with a different bank account or card
Use a different payment method
A subscriber can have more than one payment method. If you want to add an additional payment method, simply go through the process of setting up a direct debit or card again for that specific customer.
If you use a subscriber reference when creating payments, the most recently registered payment method will be used. If a subscriber has multiple payment methods and you want to have control over which method is used for each payment, then you must use either the mandate reference or the card alias reference when creating the payment.
Update the bank account
You can update and change the bank account that is associated with an existing mandate and direct debit plan. This is done by following the same steps taken to set up a direct debit, but this time setting the action property of the signMandate order item to amendBankAccount instead of sign:
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-orders');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
'started' => true,
'locale' => null,
'creditor' => [
'reference' => 'yourCreditorReference'
],
'subscriber' => [
'reference' => 'yourSubscriberReference'
],
'items' => [
[
'type' => 'signMandate',
'action' => 'amendBankAccount',
'mandate' => [
'reference' => 'theMandateReference'
]
]
]
]
));
$order = $hapiClient->sendFollow($follow);
$orderReference = $order->getState()['reference'];
You will then have to display the Checkout to the user (with a redirect link or iframe) so they can provide their new IBAN.
If you already have the IBAN at hand and don’t need it from the customer, you can update the bank account directly using the API rather than the Checkout. This is done by retrieving the relevant customer’s mandate (using the get-mandates relation), then updating the IBAN associated with that mandate using the update-bank-account relation:
// Retrieve the mandate
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#get-mandates');
$follow = new Http\Follow($rel, 'GET', [
'creditorReference' => 'yourCreditorReference',
'reference' => 'theMandateReference'
]);
$mandate = $hapiClient->sendFollow($follow);
// Update the bank account
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#update-bank-account');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody([
'iban' => 'theNewIban'
]));
$bankAccount = $hapiClient->sendFollow($follow, $mandate);
In both of the above cases, after the bank account details have been updated, the mandate reference itself remains the same.
Please note: if the new bank account belongs to a different person, you have to set up a new direct debit plan for this new customer, which requires them to sign a new mandate.
Update the payment card
There is no way of updating an existing card alias. You have to set up a new card alias and use the new reference generated in your payments requests.