Inscribir tarjeta

La inscripción de tarjeta permite asociar una tarjeta de crédito a un cliente. Con una tarjeta inscrita es posible generar cobros sin que el cliente re-ingrese sus datos.

Inscribir una tarjeta requiere 3 pasos.

  1. Iniciar inscripción y redirigir al cliente
  2. Capturar la respuesta
  3. Obtener el resultado de la inscripción

Paso 1: Iniciar inscripción y redirigir al cliente

Con un cliente previamente creado (ver creación de clientes) el primer paso es hacer una llamada a

POST /customers/{customer_id}/cards/inscriptions

especificando en la URL el identificador de cliente customer_id y como parámetro el return_url, la URL donde llegará el cliente luego de ingresar sus datos. Es necesario que el returl_url apunte a un lugar en tu sistema pues debes capturar la respuesta.

curl -X POST "https://playground.qvo.cl/customers/cus_qos_6r3-4I4zIiou2BVMHg/cards/inscriptions" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCBjb21tZXJjZSIsImFwaV90b2tlbiI6dHJ1ZX0.AXt3ep_r23w9rSPTv-AnK42s2m-1O0okMYrYYDlRyXA" \
  -d return_url="http://mi-sistema.com/return"
<?php
require 'guzzle.phar';

$client = new GuzzleHttp\Client();

$body = $client->request('POST', 'https://playground.qvo.cl/customers/cus_qos_6r3-4I4zIiou2BVMHg/cards/inscriptions', [
  'json' => [
    'return_url' => "http://mi-sistema.com/return",
  ],
  'headers' => [
    'Authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCBjb21tZXJjZSIsImFwaV90b2tlbiI6dHJ1ZX0.AXt3ep_r23w9rSPTv-AnK42s2m-1O0okMYrYYDlRyXA'
  ]
])->getBody();

$response = json_decode($body);

var_dump($response);
?>

Esta llamada retornará redirect_url. Es necesario redirigir al cliente a esa URL pues es ahí donde encontrará la interfaz para registrar su tarjeta de forma segura.

La respuesta tendrá el siguiente formato:

{
  "inscription_uid": "woi_WZa9DgYQPzPtUqMsQdoNhQ",
  "redirect_url": "https://playground.qvo.cl/webpay_oneclick/init_inscription/woi_WZa9DgYQPzPtUqMsQdoNhQ",
  "expiration_date": "2017-05-19T17:15:20.832Z"
}

ℹ Las llamadas de este tutorial usan la URL de prueba https://playground.qvo.cl. Sin embargo cuando tengas tu cuenta real (de producción) debes usar la URL https://api.qvo.cl

Paso 2: Capturar la respuesta

Cuanto el cliente termine de ingresar los datos de su tarjeta retornará con una llamada GET a el return_url proporcionado en el paso anterior. Por lo tanto, es necesario que habilites dicha ruta en tu sistema para capturar la llamada.

La ruta de la llamada contiene el parámetro uid, el identificador de la inscripción. Por ejemplo, si return_url es http://www.mi-sistema.com/return, el cliente retornará a la ruta

GET http://www.mi-sistema.com/return?uid=woi_WZa9DgYQPzPtUqMsQdoNhQ

Esto aún no garantiza la correcta inscripción de la tarjeta, es necesario verificar si la inscripción fue exitosa.

Paso 3: Obtener el resultado de la inscripción

Para verificar si la inscripción fue exitosa, se debe realizar una llamada a

GET /customers/{customer_id}/cards/inscriptions/{uid}

utilizando el identificador de la inscripción uid retornado en el paso 2 y el identificador del cliente customer_id

curl -X GET "https://playground.qvo.cl/customers/cus_qos_6r3-4I4zIiou2BVMHg/cards/inscriptions/woi_WZa9DgYQPzPtUqMsQdoNhQ" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCBjb21tZXJjZSIsImFwaV90b2tlbiI6dHJ1ZX0.AXt3ep_r23w9rSPTv-AnK42s2m-1O0okMYrYYDlRyXA"
<?php
require 'guzzle.phar';

$client = new GuzzleHttp\Client();

$body = $client->request('GET', 'https://playground.qvo.cl/customers/cus_qos_6r3-4I4zIiou2BVMHg/cards/inscriptions/woi_WZa9DgYQPzPtUqMsQdoNhQ', [
  'headers' => [
    'Authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCBjb21tZXJjZSIsImFwaV90b2tlbiI6dHJ1ZX0.AXt3ep_r23w9rSPTv-AnK42s2m-1O0okMYrYYDlRyXA'
  ]
])->getBody();

$response = json_decode($body);

var_dump($response);
?>
require 'rest-client'
require 'json'

result =
  RestClient.get 'https://playground.qvo.cl/customers/cus_qos_6r3-4I4zIiou2BVMHg/cards/inscriptions/woi_WZa9DgYQPzPtUqMsQdoNhQ', {
    Authorization: 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCBjb21tZXJjZSIsImFwaV90b2tlbiI6dHJ1ZX0.AXt3ep_r23w9rSPTv-AnK42s2m-1O0okMYrYYDlRyXA'
  }

p JSON.parse(result)
const fetch = require('node-fetch-json');

fetch('https://playground.qvo.cl/customers/cus_qos_6r3-4I4zIiou2BVMHg/cards/inscriptions/woi_WZa9DgYQPzPtUqMsQdoNhQ', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCBjb21tZXJjZSIsImFwaV90b2tlbiI6dHJ1ZX0.AXt3ep_r23w9rSPTv-AnK42s2m-1O0okMYrYYDlRyXA'
  }
}).then(function(response) {
  console.log(response);
});
import requests

r = requests.get('https://playground.qvo.cl/customers/cus_qos_6r3-4I4zIiou2BVMHg/cards/inscriptions/woi_WZa9DgYQPzPtUqMsQdoNhQ', headers={
  'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiVGVzdCBjb21tZXJjZSIsImFwaV90b2tlbiI6dHJ1ZX0.AXt3ep_r23w9rSPTv-AnK42s2m-1O0okMYrYYDlRyXA'
})

print r.json()

La respuesta contiene información sobre la tarjeta inscrita y el estado status de la inscripción. Te recomendamos almacenar el identificador de la tarjeta id pues te servirá para (realizar cobros)[] a esa tarjeta sin necesidad de volver a pedir los datos.

{
  "uid": "woi_WZa9DgYQPzPtUqMsQdoNhQ",
  "status": "succeeded",
  "card": {
    "id": "woc_bMz2iAH1mJ8M4cvv0b7IMA",
    "last_4_digits": "6623",
    "card_type": "Visa",
    "payment_type": "CD",
    "created_at": "2017-05-19T17:07:01.924Z"
  },
  "created_at": "2017-05-19T17:05:20.820Z",
  "updated_at": "2017-05-19T17:07:01.953Z"
}

El status puede tener los siguientes valores

  • succeeded: La inscripción ha sido un éxito y se adjunta card con la información de la tarjeta resultante
  • failed: La inscripción ha fracasado y se adjunta error con la información del error.

Si la inscripción fue exitosa, ya puedes generar cobros a esa tarjeta vía API, o suscribir al cliente a un plan para realizar cobros periódicos automáticos.


Ejemplos