Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

For general API request structure and authentication, see API Request & Response General Structure.

The getExternalCardId command uses the following endpoint:

POST https://your-hyp-environment-url/xpo/Relay

XML request structure

Required parameters

user - string

Your merchant username for API authentication.

password - string

Your merchant password for API authentication.

terminalNumber - string

The terminal number associated with your merchant account.

cardDataX - string

The external card token from the source payment system that needs to be transferred.

externalCGGId - string

The identifier of the external payment system or processor from which the token is being transferred.

id - string

A unique identifier for this request, used for tracking and logging purposes.

Optional parameters

cardExpiration - string (MMYY)

The expiration date associated with the external card token. Format: MMYY (e.g., "1225" for December 2025).

Response structure

Success response

Error response

Code examples

Error codes

Code
Description
Solution

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

  • doDeal - Process payments using transferred tokens

Best practices

  1. Coordinate with external systems - Ensure the source system supports token transfers and provides valid tokens

  2. Validate external system IDs - Confirm the externalCGGId is correct for your source payment processor

  3. Handle transfer failures gracefully - External token transfers may fail due to network issues or system incompatibilities

  4. Map customer records - Maintain mapping between original and new card tokens for customer account updates

  5. Test transfers thoroughly - Validate that transferred tokens work correctly for payments before going live

  6. Batch transfer operations - For large migrations, process tokens in batches to avoid overwhelming systems

  7. Monitor transfer success rates - Track which external systems have higher transfer failure rates for troubleshooting

Last updated

Was this helpful?