Check user address serviceability
Determine whether a user resides in a serviceable area before they finalize their card order. By validating the address against real-time coverage maps, you can provide immediate feedback and prevent the frustration of failed shipments or undeliverable mail.
Note:
Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process.
Use Cases
- [User-scope] You want to check whether a user requesting a physical card can be serviced and if his shipping address is within the service coverage area.
- [Admin-scope] You want to verify whether a given address is within the serviceable coverage area.
Prerequisites
[User-scope] Check Card Order Serviceability API
- The user must have an
approvedKYC. - The user profile must be in an
activestatus. - The user profile risk assessment status must not be
risk_flagged(v1). This is not applicable in v2. - The user account or wallet must be in an
activestatus. - The program is configured and enabled for physical card issuance to its users.
[Admin-scope] Check Card Order Delivery Address Serviceability API
- No KYC requirement or user active status is required to call the API.
API Workflow
1
[User-scope] Check if the user's residence is within the serviceable area
Before you allow the user to request a physical card, we must first check whether his billing / shipping address is within our logistic partners' delivery coverage.
This is to prevent physical card orders from being created but later being unable to be delivered to the cardholder.
Check Card Order Serviceability
To check if a user residence is serviceable, we can call Get Card Order Serviceability (GET /users/wallets/cards/types/{{card_type_code}}/orders/serviceability) by passing the user ID and card type code of the physical card that the user wants to request.
Check Card Order Serviceability request
curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/types/{{card_type_code}}/orders/serviceability' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••'
Check Card Order Serviceability response
[
{
"delivery_available": true,
"delivery_provider": "2GO"
}
]
2
Issue the physical card to the user
Once we have established that the delivery address of the user is serviceable, we can then proceed to issue the physical card.
Depending on the type of physical card, we can issue the following:
- Personalize physical cards by following the Link & activate a non-personalised physical card guide.
- Non-personalized physical cards by following the Request for a personalised physical card guide.
3
[Admin-scope] Check whether an address is within the serviceable area
There is also an admin-scope API that we can use to check whether a given destination address resides within the designated serviceable area of the logistics partner.
Check Card Order Delivery Address Serviceability
To check whether a given address is serviceable, we can call Check Card Order Delivery Address Serviceability (POST oauth/consumer/wallets/cards/types/{{card_type_code}}/orders/serviceability) by passing in a full valid shipping/billing address.
Note:
Remember to sanitize any trailing or leading spaces in the address fields before posting the request to reduce mismatches.
[Example 1] Check Card Order Delivery Address Serviceability request
For PH programs, when applicable, pass the following:
Optional |
Free text |
Optional |
Free text |
Yes | address_3
|
Optional | address_4
|
Yes | city
|
Yes | state
|
Optional | zipcode
|
Yes | country_code
|
Yes | country
|
curl --location 'https://{{cards_base_url}}/{{program_code}}/v2/oauth/consumer/wallets/cards/types/{{card_type_code}}/orders/serviceability' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"address_1": "8 Furong Street",
"address_2": "Nr BDO and Metrobank ATM Machine",
"address_3": "PUNTURIN",
"address_4": "NCR",
"city": "VALENZUELA_CITY_NCR",
"state": "NCR",
"zipcode": "1447",
"country": "Philippines",
"country_code": "PHL"
}'
[Example 1] Check Card Order Delivery Address Serviceability request
[
{
"delivery_available": true,
"delivery_provider": "2GO"
}
]
[Example 2] Check Card Order Delivery Address Serviceability request
curl --location 'https://{{cards_base_url}}/{{program_code}}/v2/oauth/consumer/wallets/cards/types/{{card_type_code}}/orders/serviceability' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"address_1": "Victoria Tower D Mother Ignacia St",
"address_2": "Unit 9D11A",
"address_3": "PALIGSAHAN",
"address_4": "NCR",
"city": "QUEZON_CITY_NCR",
"state": "NCR",
"zipcode": "1103",
"country": "Philippines",
"country_code": "PHL"
}
'
[Example 2] Check Card Order Delivery Address Serviceability request
[
{
"delivery_available": true,
"delivery_provider": "2GO"
}
]
On this page
- Check user address serviceability