A tokenización é o proceso de substitución dos datos reais da tarxeta (PAN) por un código seguro e único chamado token que podes gardar e usar para futuras operacións.
Exemplo real:
Tes unha tenda en liña de produtos de beleza. No primeiro pagamento, a clienta insire a súa tarxeta e ti solicitas gardala. En compras posteriores, usarás o token e o cliente non precisa volver inserir os seus datos.
- Cando queres mellorar a experiencia de compra (pagamento con 1 clic).
- Se ofreces pagamentos recorrentes ou subscricións.
- Para reducir a fricción nos dispositivos móbiles.
- Para cumprir con normativas de seguridade (sen gardar ti os datos da tarxeta).
- Cando precises usar as credenciais do cliente de xeito seguro despois da súa autorización (modelo COF: Credential On File).
| Requisito | Detalle |
| Medio de pagamento | Só aplicable a operacións con tarxeta |
| O comercio garda o PAN? | Non, Wipöp xera un token (non precisas ser PCI-DSS) |
| Cando se fai a tokenización? | No primeiro pagamento (pode ser o importe real ou importe 0) |
| Autenticación obrigatoria no primeiro uso | Si, sempre require unha compra segura (EMV 3DS sen exencións) |
| Tipos de uso posterior | Pagamento cun só clic (CIT) e pagamentos recorrentes (MIT) |
| Información devolta por Openpay | Token, últimos 4 díxitos, data de caducidade, identificador da transacción orixinal (TrxID) |
| O cliente ten que autorizalo? | Si. Debes informar explicitamente do uso futuro da súa tarxeta |
| Parámetros adicionais necesarios ao crear o cargo inicial | Débense enviar obrigatoriamente: originchannel = “ECOM” (canle de orixe) producttype = “CARD” (tipo de produto) use_cof = true (indica unha solicitude de token COF) |
| Obtención do token para a súa reutilización | O token non se recibe na resposta directa do cargo. Recíbese só a través do webhook charge.succeeded / charge.created cando se inicia COF |
| Validez do token | O token só é válido se provén do webhook oficial. Non se deben usar tokens manuais ou gardados incorrectamente |
Explícoche como facelo de dúas maneiras:
- A través da API REST de Openpay.
- Usando a libraría Java Client.
OPCIÓN 1: Usando a API REST
Paso 1: Solicitar o token (primeira operación COF)
POST /c/v1/tokens
Merchant-ID: mxxxxxxxxxxxxxxxxxxx
Authorization: Basic <base64(sk_xxxx: )>
{
"card": {
"number": "4242424242424242",
"exp_month": 12,
"exp_year": 2026,
"cvc": "123"
}
}Resultado agardado:
{
"id": "tok_1234567890abcdef",
"last4": "4242",
"exp_month": 12,
"exp_year": 2026
}Esta operación debe facerse sempre con autenticación 3DS e co consentimento explícito do cliente.
Paso 2: Usa o token para o pagamento cun só clic (CIT)
POST /v1/charges
{
"source_id": "tok_1234567890abcdef",
"method": "card",
"amount": 4999,
"currency": "EUR",
"order_id": "ORDER-1001",
"post_type": "recurrent",
"capture": true
}Só se permite o método card, as rutas e parámetros poden cambiar segundo a versión da API.
Paso 3: Usar o token para pagamentos recorrentes (MIT)
Despois da primeira operación CIT (Customer-Initiated Transaction), onde o cliente autoriza o pagamento con SCA/3DS, tokenízase a tarxeta e xérase un transaction_id que se debe usar nos futuros cargos recorrentes MIT (Merchant-Initiated Transaction).
Nos pagamentos recorrentes o cliente non está presente e, polo tanto, non se volve aplicar SCA, sempre que a operación faga referencia ao transaction_id da CIT inicial.
Endpoint
POST /c/v1/{merchantId}/chargesHeaders obrigatorios
Content-Type: application/json
Merchant-ID: {merchantId}
Authorization: Basic <Base64(sk_xxxxxx:)>Body para MIT
{ “source_id”: “tok_1234567890abcdef”,
“method”: “card”,
“amount”: 1499,
“currency”: “EUR”,
“order_id”: “ORDR00001234”,
“origin_channel”: “API”,
“product_type”: “PAYMENT_GATEWAY”,
“use_cof”: true,
“post_type”: {
“mode”: “RECURRENT”
},
“related_transaction_id”: “trx_CIT_000001”
}
OPCIÓN 2: Usando a libraría Java Client
Paso 1: Crear o token
TokenRequest tokenRequest = new TokenRequest()
.setCard(new Card()
.setNumber("4242424242424242")
.setExpMonth(12)
.setExpYear(2026)
.setCvc("123"));
Token token = client.tokenOperation().create(tokenRequest);
String tokenId = token.getId();
Paso 2: Fai o pagamento con 1 clic
CreateChargeParams params = new CreateChargeParams()
.method(ChargeMethod.CARD)
.amount(BigDecimal.valueOf(49.99))
.currency(Currency.EUR)
.orderId("ORDER-1001")
.sourceId(tokenId)
.postType(new PostType(PostTypeMode.RECURRENT))
.capture(true);Charge charge = client.chargeOperation().create(params);
Que datos devolve o servizo?
Ao solicitar o token, Wipöp devolve:
- token_id: código de referencia único (non sensible).
- Últimos 4 díxitos da tarxeta (last4)
- Data de caducidade (exp_month e exp_year)
- TrxID: identificador da transacción orixinal, necesario para os pagamentos recorrentes MIT
| Código/erro | Causa posible | Solución suxerida |
| 401 Unauthorized | Falta ou erro na API Key | Verifica a cabeceira Authorization |
| 403 Forbidden | O comercio no ten habilitada a operativa | Contacta co servizo de asistencia de Wipöp |
| 422 Unprocessable | Tarxeta non válida, caducada ou mal formatada | Revisa os datos enviados e téntao de novo |
| 400 Missing params | Mandatory fields not sent | Make sure to include all fields of the token |
| related_transaction_id required | The initial operation was not referenced | Mandatory for MIT according to PSD2 |
| VC / BC / AC | Tipo de rexeitamento bancario: VC: Validación do cliente BC: Validación do banco AC: Autorización do adquirente | Útil para clasificar a orixe do fallo. |
