getExternalCardId
Overview
The getExternalCardId command transfers external card tokens from other payment processors or systems into the Hyp platform. This command enables merchants to migrate stored card tokens between different payment systems while maintaining PCI compliance.
Use cases
Use getExternalCardId when you need to:
Migrate stored card tokens from another payment processor to Hyp
Import existing customer payment methods during system transitions
Consolidate card tokens from multiple payment systems
Transfer card data between different merchant accounts or processors
Maintain customer-saved payment methods during platform changes
Request structure
The getExternalCardId command uses the following endpoint:
POST https://your-hyp-environment-url/xpo/Relay
XML request structure
Required parameters
Optional parameters
Response structure
Success response
Error response
Code examples
Error codes
000
Permitted transaction
External token transferred successfully
425
Failed to get response from external server
This error occurs after a timeout was reached and the local gateway failed to get response from the remote gateway. Check network connectivity and external server availability
426
Failed to find external server details for sharing cardid
The externalCGGId request parameter could not be found in CG Gateway configuration. Verify the external system ID is correct
452
No privileges found for sharing cardid
The username sent in the request is not authorized to use this command. Contact support to enable permissions for token sharing
Related commands
doDeal- Process payments using transferred tokens
Best practices
Coordinate with external systems - Ensure the source system supports token transfers and provides valid tokens
Validate external system IDs - Confirm the externalCGGId is correct for your source payment processor
Handle transfer failures gracefully - External token transfers may fail due to network issues or system incompatibilities
Map customer records - Maintain mapping between original and new card tokens for customer account updates
Test transfers thoroughly - Validate that transferred tokens work correctly for payments before going live
Batch transfer operations - For large migrations, process tokens in batches to avoid overwhelming systems
Monitor transfer success rates - Track which external systems have higher transfer failure rates for troubleshooting
Last updated
Was this helpful?