1. Home
2. Soluciones de integración
3. Opciones
4. DCC a través de DirectLink

1. Introducción

La Conversión dinámica de divisas (DCC) electrónica permite a sus clientes elegir entre su divisa preferida y su divisa predeterminada. Se trata de una opción que se puede habilitar a su solicitud.

Con DirectLink, el proceso DCC se divide en dos etapas:

1. Solicita los detalles de DCC, en función del número BIN de la tarjeta del cliente
2. Solicita el pago con una llamada a DirectLink general, incluidos algunos parámetros adicionales (para proporcionar los detalles de DCC elegidos obtenidos anteriormente)

2. Solicitud de detalles de DCC a través de la API de DCC Worldline

Si desea recuperar la oferta de DCC para el número de tarjeta usado por el cliente, debe utilizar el API de DCC. Esta API devolverá un documento XML que contiene los valores de DCC que Worldline ha recuperado de su proveedor de DCC.

Existen algunas condiciones si desea utilizar el API DCC:

• La opción DirectLink debe estar habilitada en su cuenta.
• La opción DCC debe estar habilitada en su cuenta.
• Debe poder ofrecer compatibilidad con la marca de tarjeta para la que solicite los tipos de DCC. Por ejemplo, no puede solicitar tipos de DCC para una tarjeta de crédito VISA si no admite pagos de VISA o si no admite pagos DCC para este tipo de tarjeta.

2.1 Parámetros y URL de API

Las siguientes URL se utilizan para ejecutar el API de DCC Worldline:

• PRUEBA: https://ogone.test.v-psp.com/ncol/test/getDCCRates.asp
• PROD: https://secure.ogone.com/ncol/prod/getDCCRates.asp

Para recibir una respuesta de tipo de DCC válida, deben enviarse los siguientes parámetros al API de DCC:

Campo / Formato	Descripción
AMOUNT Numeric	La cantidad original que se va a convertir (importe x 100)
BIN 6 numbers	Los primeros dígitos (número BIN) de la tarjeta del cliente
CONVCCY 3 alphanumeric characters	La divisa a la que debe convertirse el importe
CURRENCY 3 alphanumeric characters	La divisa original del importe
ORDERID Alphanumeric	La referencia de pedido única del comerciante
PSPID -	PSPID del comerciante
PSWD -	Contraseña del usuario API
SHASIGN -	Resumen (cadena de hash) para autenticar los datos
USERID -	ID de usuario para cuenta de varios usuarios

Si alguno de estos campos no se proporciona correctamente, se producirá un error.

Nota:

• Tanto el parámetro BIN como el CONVCCY son obligatorios, ya que debe determinarse a qué divisa tiene que convertirse el importe. BIN es obligatorio si no se proporciona ningún CONVCCY. CONVCCY es obligatorio si no se proporciona ningún BIN y, en caso contrario, se ignora. Esto significa que si se proporcionan ambos, el BIN tendrá prioridad sobre CONVCCY y la nueva divisa vendrá determinada en función de este BIN. En cualquier caso, le recomendamos encarecidamente que utilice el BIN en lugar del parámetro CONVCCY.
• La referencia de pedido suministrada con el parámetro ORDERID es un parámetro obligatorio que debe ser único. Es importante que esta referencia se utilice posteriormente de nuevo al procesar la transacción real, ya que los tipos de DCC se anexarán a este pedido específico. Debe usarse la misma referencia de pedido si se realizan varias consultas de tipo de DCC para la misma transacción.

2.2 Cálculo SHA

A continuación, se muestra cómo funciona el cálculo SHA para la solicitud de DCC. Aunque el principio es el mismo que para el SHA de prepago, no deben confundirse, ya que son dos procesos independientes.

Campos AMOUNT: 1.50 --> 150 BIN: 411111 CURRENCY: EUR ORDERID: order00001 PSPID: MyPSPID PSWD: MySecretPswd51 USERID: MyAPIUser Frase de contraseña SHA (en Información técnica): MySecretSig1875!? Cadena para la que se va a generar el hash AMOUNT=150MySecretSig1875!?BIN=411111MySecretSig1875!?CURRENCY=EURMySecretSig1875!? ORDERID=order00001MySecretSig1875!?PSPID=MyPSPIDMySecretSig1875!?PSWD=MySecretPswd51 MySecretSig1875!?USERID=MyAPIUserMySecretSig1875!? Resumen resultante (SHA-1): EFA8DD0C297CBA45DD7ADBEAF7CA4699C8F3C19B

Nota: Si desea proporcionar tanto el parámetro BIN como el CONVCCY, ambos deben ir con hash, aunque solo el BIN se tenga en cuenta en el proceso.

Campos: AMOUNT: 1.50 --> 150 BIN: 411111 CONVCCY: JPY CURRENCY: EUR ORDERID: order00001 PSPID: MyPSPID PSWD: MySecretPswd51 USERID: MyAPIUser Frase de contraseña SHA (en Información técnica): MySecretSig1875!? Cadena para la que se va a generar el hash: AMOUNT=150MySecretSig1875!?BIN=411111MySecretSig1875!?CONVCCY=JPYMySecretSig1875!? CURRENCY=EURMySecretSig1875!?ORDERID=order00001MySecretSig1875!?PSPID=MyPSPID MySecretSig1875!?PSWD=MySecretPswd51MySecretSig1875!?USERID=MyAPIUserMySecretSig1875!? Resumen resultante (SHA-1): 3AA6212395739EA34C0853DB060B4B290EAB3422

2.3 Respuesta de API

La respuesta de la llamada de API es siempre un documento estructurado XML que contiene toda la información necesaria para continuar con la segunda etapa del proceso de transacción.

2.3.1 Respuesta correcta

Si los tipos de DCC se han obtenido correctamente, el XML tendrá el siguiente formato:

<dccResponse>
<orderid></orderid>	-> Referencia de pedido única del comerciante (alfanumérica)
<commPerc></commPerc>	-> Porcentaje de comisión (numérico)
<convAmt></convAmt>	-> Importe tras la conversión (x 100)
<convCcy></convCcy>	-> Divisa de conversión (3 caracteres)
<reference></reference>	-> Referencia de DCC (puede estar vacía)
<exchRate></exchRate>	-> Tipo de cambio (numérico)
<exchRateSource></exchRateSource>	-> Fuente que ha proporcionado los tipos de DCC
<exchRateTS></exchRateTS>	-> Marca de tiempo de los tipos de DCC (FechaHora)
<marginPerc></marginPerc>	-> Porcentaje de margen (numérico)
<valid></valid>	-> Validez de la oferta (en horas) (numérico)
</dccResponse>

La marca de tiempo de cuándo se capturaron los tipos de DCC se suministra en el tipo de datos FechaHora de XML predeterminado, que tiene el formato “AAAA-MM-DDThh:mm:ss”, donde:

• AAAA indica el año
• MM indica el mes
• DD indica el día
• T indica el inicio de la sección de tiempo necesaria
• hh indica la hora
• mm indica el minuto
• ss indica el segundo

2.3.2 Respuesta errónea

Si se ha producido algún error durante el procesamiento de la llamada de API a DCC o, por algún motivo técnico (por ejemplo, no se ha contactado con el proveedor de DCC, los datos proporcionados no eran correctos, etc.), se produce un error a través de la respuesta XML. Una llamada de API a DCC errónea tiene el siguiente formato:

<dccResponse>
<error>
<code></code>	-> Código de error (numérico)
<desc></desc>	-> Descripción del error (cadena)
</error>
</dccResponse>

3. Solicitud de pago de DCC

Después de haber obtenido los posibles detalles de DCC y de habérselos mostrado al cliente, este debe tener la elección de usarlos o no. Por ejemplo, pagar en su divisa propia (se produce una conversión entre la divisa de su propia tarjeta y la divisa del comerciante) o pagar en su divisa predeterminada (no se realizará ninguna conversión de divisa).

A continuación, explicamos el caso en que el cliente debe elegir pagar en su propia divisa, lo que significa que hará uso de la conversión de divisa propuesta. Se trata del caso más avanzado, ya que será necesario que añada parámetros adicionales a la solicitud de DirectLink, con el fin de poder proporcionar los valores de DCC elegidos.

Sin embargo, en ambos casos (se acepte o no DCC), estará obligado a proporcionar un parámetro adicional común que sea el indicador de DCC. Este indicador DCC especifica si el cliente ha aceptado o no la propuesta de DCC.

3.1 Parámetros

Los parámetros que el comerciante debe proporcionar son los siguientes:

Campo	Descripción	Formato	Obligatorio
DCC_COMMPERC Numérico	Porcentaje de comisión		N
DCC_CONVAMOUNT* Numérico	Cantidad convertida	Numérico	S
DCC_CONVCCY* Alfanumérico, máx. 3	Divisa convertida		S
DCC_EXCHRATE* Numérico	Tipo de cambio	Numérico	S
DCC_EXCHRATETS* [aaaa-mm-dd hh:mm:ss]	Fecha de tipo de cambio		S
DCC_INDICATOR* 0 o 1	Indicador DCC (indica si el cliente ha aceptado o no la propuesta de DCC). Valores posibles: 0: El cliente paga en la divisa del comerciante (no se realiza conversión) 1: El cliente paga en su propia divisa (se acepta la conversión) Este parámetro siempre es obligatorio para indicar que se ha utilizado DCC para esta transacción.		S
DCC_MARGINPERC* Numérico	Porcentaje de margen		S
DCC_REF Alfanumérico, máx. 80	Referencia del DCC		N
DCC_SOURCE Alfanumérico, máx. 32	Fuente de tipo de cambio		S
DCC_VALID* Numérico	Validez de tipo de cambio (expresado en horas)	Numérico	S
ORDERID* (**) Numérico	Referencia de pedido del comerciante	Alfanumérico	S

_{(** El ORDERID debe coincidir con el usado durante la llamada de API a DCC. Si no se proporciona el ORDERID o no coincide con el usado durante una llamada de API, la transacción se bloqueará).}

Todos estos valores se proporcionan a través de la API de DCC Worldline cuando se realiza la solicitud de DCC (etapa 1).

3.2 Validez de oferta de DCC caducada

Cada DCC ofrece su propio tiempo de validez, que se puede calcular añadiendo los parámetros de DCC_VALID (período de validez expresado en horas) al valor de fecha y hora (datetime) proporcionado en DCC_EXCHRATETS. Si detectamos que se ha suministrado una oferta de DCC junto a la transacción que ya ha caducado, existen dos posibles resultados, dependiendo de su configuración. Tenga en cuenta que se trata del único caso relevante en caso de que el cliente haya aceptado la oferta de DCC (DCC_INDICATOR = 1). Si no ha aceptado la oferta de DCC no tendrá importancia que Worldline revise la validez de la oferta rechazada.

El primer caso se produce cuando ha configurado bloquear la transacción si la oferta de DCC ha caducado. Worldline Esto sucede así y se devuelve el número de error general 50001111.

En el segundo caso no bloqueamos la transacción. En lugar de esto, recuperamos una nueva oferta de DCC nosotros mismos. Para ello, hacemos uso de la divisa y el importe que nos han suministrado en la transacción original, y esta oferta se acepta de forma automática (tenga en cuenta que los tipos pueden ser diferentes de los caducados que haya enviado).

3.3 Posibles errores

ID de error	Descripción
50001111	Código de error general
50001118	PSPID desconocido o inactivo
50001122	Divisa no válida o inactiva
50001120	Código de divisa desconocido
50001144	Entidad adquirente no encontrada en función de la entrada
50001146	Configuración de DCC no encontrada para PSPID + Marca
50001184	Discordancia de SHA
30131001	Cantidad no válida

Existen algunos posibles problemas cuando un comerciante utiliza DCC en DirectLink. Todos ellos son bastante claros, pero como utilizamos un código de error general (50001111) para algunos, serán necesarias algunas explicaciones.

Posibles errores:

• La validez de la oferta de DCC ha caducado. Esta se calcula en función del DCC_EXCHRATETS más DCC_VALID (expresado en horas).
• Se utiliza un valor incorrecto en uno de los campos, por ejemplo, DCC_INDICATOR debe ser 0 o 1, DCC_EXCHRATETS debe ser una fecha bien formateada, DCC_CONVAMOUNT debe ser numérico, etc.
• Los parámetros de DCC suministrados por el comerciante no coinciden con los que se han recuperado a través de la llamada de API a DCC
• La marca de la tarjeta solicitada no coincide con la suministrada en el parámetro BRAND
• La opción DCC no está habilitada en la cuenta del comerciante
• La tarjeta suministrada no es apta para transacciones DCC
• Divisa no válida suministrada a través de DCC_CONVCCY