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.
This feature is only available to select regions and partners subscribed to the card delivery service.
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 profile risk assessment status must not be
risk_flagged. - The user profile must be in an
activestatus. - The user must have an
approvedKYC or KYB status. - 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:
- Personalised 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.
Check Card Order Delivery Address Serviceability request
For PH programs, when applicable, pass the code value from Get Line 3 (Barangay) Enumeration GET v2/users/enumerations/line_3 in the address_3 field.
Otherwise, the field can be opened for free text.
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": "Purok 2",
"address_2": "-",
"address_3": "LEGASPI",
"address_4": "Region V",
"city": "Legazpi City",
"state": "ALBAY",
"zipcode": "4500",
"country": "Philippines",
"country_code": "PHL"
}'Check Card Order Delivery Address Serviceability request
[
{
"delivery_available": true,
"delivery_provider": "2GO"
}
]
On this page
- Check user address serviceability