WooCommerce

20 agosto, 202414 mayo, 2020 por user

WooCommerce

¿Qué es WooCommerce?

WooCommerce es un plugin para sitios basados en WordPress que le permite a sus usuarios convertirlos en comercios electrónicos de manera fácil y rápida.

Los plugins de Openpay para WooCommerce le permite configurar y añadir nuestros métodos de pago soportados (tarjeta de crédito/débito, tiendas y PSE) dentro del flujo compra de su tienda en línea.

Versiones soportadas

WordPress 6.3
WooCommerce 8.0.2
WooSubscriptions 5.4.0
PHP 8.2

Requerimientos

Es necesario que el servidor donde se encuentre alojada su tienda de WordPress cuente con las siguientes características:

Versión instalada de PHP 5.6 o mayor.
Versión instalada de MySQL 5.0 o mayor.
Extensión de Apache mod_rewrite habilitada.
Versión instalada de WordPress 4.9 o mayor.
Versión instalada del plugin WooCommerce hasta 8.0.2.
Extensión de PHP CURL habilitada.
Contar con un certificado SSL para su comercio electrónico.

Instalación

En su panel de administración de WordPress, dirigirse a la sección Plugins -> Añadir nuevo, ubicado en el menú lateral,

En el buscador, escribe la palabra clave Openpay para buscar las opciones de pago disponibles.

En los resultados de la búsqueda, identifica el plugin del método de pago deseado y hacer clic en Install Now. Al terminar la instalación, se bebe activar el plugin.

Nota: Deberá seguir esta guía por cada método de pago que desee habilitar en su comercio.

Configuración de los módulos

1. En su panel de administración de WordPress, dirigirse a la sección WooCommerce -> Settings, ubicado en el menú lateral.

2. Modificar el valor Currency del formulario por la opción Colombian Peso ($). Guardar los cambios mediante el botón Save changes ubicado al final del formulario.

3. Para activar y desactivar las opciones de pagos, deberá seguir los siguientes pasos.

a. Dirigirse a la pestaña Payments ubicada en la parte superior de las configuraciones de Woocommerce.

b. Activar la opción de pago deseada.

c. Dar clic en el bóton Manage para comenzar con la configuración.

4. Identificar las credenciales de API asignadas a su comercio dentro del panel de administración de Openpay.

Para ver las credenciales, dar clic en el engrane del menú superior derecho y luego seleccionar la opción Credenciales de API

5. Completar la configuración del apartado de Openpay, contemplando los siguientes tópicos:

Configuraciones Generales Openpay

Habilitar módulo: Habilita el uso de Openpay como plataforma de pagos.
Modo de pruebas: Determina si el plugin va a funcionar en entorno de pruebas (Sandbox) o Producción.
País: Seleccionar el país donde se encuentra (Colombia, México).
Credenciales de Openpay (Merchant ID, Secret Key, Public Key): Credenciales de API para utilizar el plugin (ya sea en modo Sandbox o Producción). Copiar y pegar cada dato (obtenido en el Paso anterior) como corresponda.
¿Como procesar el cargo?. – Define el tipo de cargo que se realizará: 3Dsecure, Directo ó Autenticación selectiva.
- Directo: Se realizará una evaluación del cargo y se rechazará si el sistema antifraude detectó alguna anomalía.
- 3D Secure: Se realizará un redireccionamiento al banco para que el cliente sea autenticado en su banco.

Configuraciones pago con tarjeta

Guardar tarjetas: Permite a los usuarios registrados guardar sus tarjetas crédito/débito para agilizar sus futuras compras.
Cuotas: Puede habilitar o deshabilitar pagos con cuotas seleccionando el número de cuotas disponibles.
IVA: Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.

Configuraciones pago en tienda

(La instalación del plugin y configuración inicial para el plugin de pago en tiendas es similar a la descrita arriba)

Payment deadline: Defina la cantidad de horas de validez para realizar un pago en Tiendas de Conveniencia.
IVA: Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.

Configuración pago vía PSE

IVA: Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.

6. Guardar los cambios en la configuración dando clic sobre el botón Guardar los cambios ubicado al final del formulario.

Notificación de pagos en tiendas y PSE.

Los plugins Openpay están preparados para recibir las notificaciones de pago de forma automática, es decir, sin la necesidad de configurar su cuenta de Openpay o el plugin. Las notificaciones se envían al comercio cuando los pagos han sido realizados o cuando una referencia ha vencido.

Importante: Los plugins asumen que la tienda se encuentra en la raiz del dominio, por lo que se crea el webhook tomando como base está url.

Pago en tiendas

https://[eCommerce domain]/wc-api/Openpay_Stores

PSE

https://[eCommerce domain]/wc-api/Openpay_PSE

Verficación de Webhook.

Es importante verificar que el webhook se haya creado correctamente en Openpay.

NOTA: Recuerde que no es necesario agregar el webhook manualmente, al guardar la configuración de módulo este lo crea de forma automática.

1.- En su panel de configuración de Openpay ir a Ajustes (icono de engrane) -> Configuraciones

2.- Ubicar el apartado de Webhook, si el webhook fue configurado correctamente habrá un registro en estado Verificado.

Magento 2

31 enero, 202514 mayo, 2020 por user

Magento 2

¿Qué es Magento?

Magento es una plataforma que permite la gestión de contenidos web para un comercio electrónico, ofreciendo una solución flexible y escalable sobre la cual se puede basar cualquier proyecto de tienda en línea.

El plugin de Openpay para Magento le permite configurar y añadir nuestros métodos de pago soportados (tarjeta de crédito/débito, tiendas de conveniencia y SPEI) dentro del flujo compra de su comercio electrónico.

Versiones soportadas.

Magento Open Source Edition (Magento Community) 2.1.1 en adelante.
Magento Adobe Commerce (Magento Enterprise)
Magento Commerce Cloud Edition (Magento Cloud)

Requerimientos.

Es necesario que el servidor donde se encuentre alojado su comercio electrónico basado en Magento 2 cuente con las siguientes características:

Versión instalada de PHP 8.1.
Versión instalada de MySQL 8.0 o mayor.
Contar con un certificado SSL para su comercio electrónico.

Instalación.

Para la instalación de extensiones (plugins) en Magento 2 es necesario aplicar una serie de comandos en la terminal del servidor donde este alojada nuestra plataforma.

Para implementar las 3 diferentes formas de pago en tu tienda, será necesario instalar y habilitar cada uno de ellos por separado.

1.- Ingresar desde la terminal de nuestro servidor a la carpeta raíz del proyecto de Magento.

2.- Ingresar los siguientes comandos, los cuales descargarán las extensiones al proyecto y adicional a ello descargarán la librería de Openpay de PHP.

Módulo de pagos con tarjeta de crédito

 composer require openpay/magento2-cards:3.4.*

Módulo para pagos en efectivo

# Para versiones de Magento < 2.3.0 
composer require openpay/magento2-stores:~3.1.0
# Para versiones de Magento >= 2.3.0
composer require openpay/magento2-stores:~3.5.0

# Para versiones de Magento >= 2.3.5
composer require openpay/magento2-stores:~4.1.0

Módulo para pagos vía PSE

#Para versiones de Magento < 2.3.0 
composer require openpay/magento2-banks:~3.1.0 
# Para versiones de Magento >= 2.3.0
composer require openpay/magento2-banks:~3.5.0

# Para versiones de Magento >= 2.3.5
composer require openpay/magento2-banks:~4.1.0

3.- Después se procede a habilitar los módulos, actualizar y limpiar cache de la plataforma.

php bin/magento module:enable Openpay_Cards --clear-static-content
php bin/magento module:enable Openpay_Stores --clear-static-content
php bin/magento module:enable Openpay_Banks --clear-static-content
php bin/magento setup:upgrade
php bin/magento cache:clean

Configuración de módulos.

1.- Identificar las credenciales de API asignadas a su comercio dentro del panel de administración de Openpay.

2.- Aparecerá una pantalla como la que se muestra a continuación.

3.- En su panel de administración de Magento 2, dirigirse a la sección Stores -> Configuration.

4. Una vez dentro de la pantalla de Configuración, ubicar en el menú lateral izquierdo Sales -> Payment Methods.

5.- Le aparecerán los Módulos que instaló.

Configurar Openpay Tarjetas.

Configuración general.

Habilitado (Enabled).- Para habilitar el modo de pago.
Sandbox.- Determina si el plugin va a funcionar en entorno de pruebas (Sandbox).
Título (Title).- Nombre del método de pago que se mostrará en la tienda.
Credenciales de Openpay (Merchant ID, Llave Secreta, Llave Pública).- Credenciales de API para utilizar el plugin (ya sea en modo Sandbox o Producción). Copiar y pegar cada dato (obtenido en el Paso 1) como corresponda.
País.- Seleccionar el país donde se encuentra (Colombia, México).

Configuración pago con tarjeta.

¿Cómo procesar el cargo?.- Define el tipo de cargo que se realizará: Directo, 3Dsecure o Autenticación Selectiva.
- Directo: Se realizará una evaluación del cargo y se rechazará si el sistema antifraude detectó alguna anomalía.
- 3D Secure: Se realizará un redireccionamiento al banco para que el cliente sea autenticado en su banco.
Guardar tarjetas.- Permite a los usuarios registrados guardar sus tarjetas crédito/débito para agilizar sus futuras compras.
Tipos de tarjetas (Credit card types).-Deberán de estar seleccionados los 3 tipos de tarjetas para aceptar todo tipo de tarjetas permitidas por Openpay.
IVA.- Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.
Cuotas.- Puede habilitar o deshabilitar pagos con cuotas seleccionando el número de cuotas disponibles.
Configuración de países permitidos (Payment from applicable countries, payment from specific countries).- Puede dejarse con la configuración por default que tiene o bien puede definirse únicamente a Colombia.
Orden (Sort order).- Orden en que se mostrará este método de pago.

Configuración pagos en tiendas.

Fecha límite para pago (Payment deadline).- Definir el número de horas que tendrá el cliente una vez emitido el recibo de pago para efectuar éste.
IVA.- Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.
Configuración de países permitidos (Payment from applicable countries, payment from specific countries).- Puede dejarse con la configuración por default que tiene o bien puede definirse únicamente a Colombia.
Orden (Sort order).- Orden en que se mostrará este método de pago.

Configuración pago con PSE.

Configuración de países permitidos (Payment from applicable countries, payment from specific countries).- Puede dejarse con la configuración por default que tiene o bien puede definirse únicamente a Colombia.
IVA.- Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.
Orden (Sort order).- Orden en que se mostrará este método de pago.

6. Cuando finalize las configuraciones de su preferencia, dar clic en el botón de Save Config.

7.- Una vez que se hayan guardado los cambios, Magento te solicitará que limpies la cache del sistema, dar clic en Cache Management.

8.- En la pantalla que le aparecerá, dar clic en Flush Magento Cache.

Una vez hecho esto, tu tienda dispondrá de las formas de pago que ofrece Openpay.

Notificaciones de pago en tienda.

Importante: Los plugins asumen que la tienda se encuentra en la raíz del dominio, por lo que se crea el webhook tomando como base está url.

https://[eCommerce domain]/openpay/index/webhook

Verificación de Webhook.

Nota: Recuerde que no es necesario agregar el Webhook manualmente, al guardar la configuración del módulo este lo crea de forma automática.

Es importante verificar que el Webhook haya sido creado de forma correcta en Openpay.

1.- En su panel de configuración de Openpay ir a Ajustes (icono de engrane) -> Configuraciones.

2. Ubicar el apartado de Webhooks. Si el webhook fue configurado correctamente habrá un registro en estado Verificado.

Contenido

Magento

18 julio, 202214 mayo, 2020 por user

Magento

¿Qué es Magento?

Por motivos de seguridad, a partir del 30 de junio del 2020 Openpay dejará de soportar las actualizaciones de Magento 1. Invitamos a los usuarios a migrar sus plataforma a la brevedad antes de ser vulnerables a violaciones de seguridad que nos impidan ofrecerles el servicio.

Requerimientos

Es necesario que el servidor donde se encuentre alojado su comercio electrónico basado en Magento cuente con las siguientes características:

Magento Community Edition 1.9.2.4 en adelante.
Versión instalada de PHP 5.4 o mayor.
Versión instalada de MySQL 5.0 o mayor.
Contar con un certificado SSL para su comercio electrónico.

Instalación

1. Solicite el archivo ZIP con los contenidos del plugin. Puede solicitar el plugin al área de Soporte Openpay.

2. En su panel de administración de Magento, dirigirse a la sección System -> Magento Connect -> Magento Connect Manager.

3. Cargar el archivo descargado en el Paso 1 dentro del formulario de la sección Manage Existing Extensions, dar clic en Upload.

4. Confirmar la instalación del plugin.

Configuración

Identificar las credenciales de API asignadas a su comercio dentro del panel de administración de Openpay

Para ver las credenciales, dar clic en el engrane del menú superior derecho y luego seleccionar la opción Credenciales de API

2. En su panel de administración de Magento, dirigirse a la sección System -> Configuration.

3. Expandir el apartado States Options y seleccionar todos los países a los cuales desea vender. Guardar los cambios mediante el botón Save Config, ubicado en la esquina superior derecha de la pantalla.

4. Dar clic en el enlace Sales -> Payment Methods, ubicado en el menú lateral

5. Completar el apartado Openpay – Configuración General contemplando los siguientes tópicos:

Modo pruebas (Sandbox): Determina si el plugin va a funcionar en entorno de pruebas (seleccionando Enable) o Producción (seleccionando Disable).
Llave pública, ID de comercio, Llave privada: Credenciales de API para utilizar el plugin (ya sea en modo Sandbox o Producción). Copiar y pegar cada dato (obtenido en el Paso 1) como corresponda.

6. Completar el apartado Openpay – Tarjetas de crédito y débito utilizando como referencia la siguiente imagen:

7. Guardar los cambios mediante el botón Save Config, ubicado en la esquina superior derecha de la pantalla.

Contenido

API

5 julio, 202413 mayo, 2020 por user

Introducción

La API de Openpay está diseña sobre REST, por lo tanto encontrarás que las URL están orientadas a recursos y se usa códigos de respuesta HTTP para indicar los errores en la API.

Todas las respuestas de la API están en formato JSON, incluyendo errores.

En el caso de usar los clientes existentes del API de Openpay (Java, Php, C#), las respuestas son específicamente del tipo definido en dichos clientes en sus respectivos lenguajes.

API Endpoints

La API REST de Openpay tiene un ambiente de pruebas (sandbox) y un ambiente de producción. Usa las credenciales que se generaron al momento de tu registro para realizar la integración de tu sistema con Openpay. Una vez que estes listo para pasar a producción y tu solicitud sea aprobada, se generarán nuevas credenciales para acceder al ambiente de producción.

La siguientes URIs forman la base de los endpoints para los ambientes soportados:

Pruebas, URI base:
https://sandbox-api.openpay.co
Producción, URI base:
https://api.openpay.co

Un endpoint completo esta formado por la URI base del ambiente, el identificador del comercio y el recurso.

Por ejemplo, si queremos crear un nuevo cliente, el endpoint sería:

POST https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers

Para crear una petición completa es necesaria envíar las cabeceras HTTP correctas y la información en formato JSON.

Todos los ejemplos de está documentación están apuntados al ambiente de pruebas.

Recursos disponibles

a) Por Comercio

/v1/{MERCHANT_ID}/...

/fees
/fees/{FEE_ID}
/charges
/charges/{TRANSACTION_ID}
/pse
/cards
/cards/{CARD_ID}
/customers
/customers/{CUSTOMER_ID}
/plans
/plans/{PLAN_ID}
/tokens
/tokens/{TOKEN_ID}

b) Por Cliente

/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/...

/cards
/cards/{CARD_ID}
/charges
/charges/{TRANSACTION_ID}
/pse
/subscriptions
/subscriptions/{SUBSCRIPTION_ID}

Autenticación

Para realizar peticiones a la API de Openpay, es necesario enviar la llave de API (API Key) en todas tus llamadas a nuestros servidores. La llave la puedes obtener desde el dashboard.

Existen 2 tipos de llaves de API:

Privada.- Para llamadas entre servidores y con acceso total a todas las operaciones de la API (nunca debe ser compartida).

Manten esta llave segura y nunca la compartas con nadie.

Pública.- Sólo se debe utilizar en llamadas desde JavaScript. Esta llave sólo tiene permitido realizar crear tarjetas o crear tokens

Para hacer llamadas con tu llave pública utiliza la librería Openpay.js

Para la autenticación al API debes usar autenticación de acceso básica, donde la llave de API es el nombre de usuario. La contraseña no es requerida y debe dejarse en blanco por fines de simplicidad.

Por razones de seguridad todas las peticiones deben ser vía **HTTPS**.

cURL

PHP

JAVA

cURL

Ejemplo de autenticación

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/charges \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

El parámetro -u se ocupa para realizar la autenticación HTTP Basic

(al agregar dos puntos después de la llave privada se previene el uso de contraseña)

Producción
Solo es necesario usar la URI base https://api.openpay.co

PHP

Ejemplo de autenticación

<?
//Por default se usa el ambiente de sandbox
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c4875b178ce26348b0fac', 'CO','127.0.0.1');
?>

Producción

<?
Openpay::setProductionMode(true);
?>

JAVA

Ejemplo de autenticación

//Sandbox
final OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "moiep6umtcnanql3jrxp", "sk_3433941e467c4875b178ce26348b0fac", "127.0.0.1");

//Produccion
final OpenpayAPI api = new OpenpayAPI("https://api.openpay.co", "moiep6umtcnanql3jrxp", "sk_3433941e467c4875b178ce26348b0fac", "127.0.0.1");

Producción

//Solo es necesario usar la URI base https://api.openpay.co

Ejemplo de autenticación

//Sandbox
OpenpayAPI openpayAPI = new OpenpayAPI("sk_3433941e467c4875b178ce26348b0fac", "moiep6umtcnanql3jrxp", "127.0.0.1");
openpayAPI.Production = false; // Default value = false

//Produccion
OpenpayAPI openpayAPI = new OpenpayAPI("sk_3433941e467c4875b178ce26348b0fac", "moiep6umtcnanql3jrxp", "127.0.0.1");
openpayAPI.Production = true;

Producción

openpayAPI.Production = true;

Errores

Openpay regresa objetos de JSON en las respuestas del servicio, incluso en caso de errores por lo que cuando exista un error.

Objeto Error

Propiedad	Descripción
category	*string* request: Indica un error causado por datos enviados por el cliente. Por ejemplo, una petición inválida, un intento de una transacción sin fondos. internal: Indica un error del lado de Openpay, y ocurrira muy raramente. gateway: Indica un error durante la transacción de los fondos de una tarjeta a la cuenta de Openpay o de la cuenta hacia un banco o tarjeta.
error_code	*numeric* El código del error de Openpay indicando el problema que ocurrió.
description	*string* Descripción del error.
http_code	*string* Código de error HTTP de la respuesta.
request_id	*string* Identificador de la petición.
fraud_rules	*array* Arreglo con la lista de coincidencia de reglas definidas para deteccion de fraudes.

Códigos de error

Generales

Código	Error HTTP	Causa
1000	500 Internal Server Error	Ocurrió un error interno en el servidor de Openpay
1001	400 Bad Request	El formato de la petición no es JSON, los campos no tienen el formato correcto, o la petición no tiene campos que son requeridos.
1002	401 Unauthorized	La llamada no esta autenticada o la autenticación es incorrecta.
1003	422 Unprocessable Entity	La operación no se pudo completar por que el valor de uno o más de los parametros no es correcto.
1004	503 Service Unavailable	Un servicio necesario para el procesamiento de la transacción no se encuentra disponible.
1005	404 Not Found	Uno de los recursos requeridos no existe.
1006	409 Conflict	Ya existe una transacción con el mismo ID de orden.
1007	402 Payment Required	La transferencia de fondos entre una cuenta de banco o tarjeta y la cuenta de Openpay no fue aceptada.
1008	423 Locked	Una de las cuentas requeridas en la petición se encuentra desactivada.
1009	413 Request Entity too large	El cuerpo de la petición es demasiado grande.
1010	403 Forbidden	Se esta utilizando la llave pública para hacer una llamada que requiere la llave privada, o bien, se esta usando la llave privada desde JavaScript.

Almacenamiento

Código	Error HTTP	Causa
2002	409 Conflict	La tarjeta con este número ya se encuentra registrada en el cliente.
2003	409 Conflict	El cliente con este identificador externo (External ID) ya existe.
2004	422 Unprocessable Entity	El dígito verificador del número de tarjeta es inválido de acuerdo al algoritmo Luhn.
2005	400 Bad Request	La fecha de expiración de la tarjeta es anterior a la fecha actual.
2006	400 Bad Request	El código de seguridad de la tarjeta (CVV2) no fue proporcionado.
2007	412 Precondition Failed	El número de tarjeta es de prueba, solamente puede usarse en Sandbox.
2009	412 Precondition Failed	El código de seguridad de la tarjeta (CVV2) no es valido.

Tarjetas

Código	Error HTTP	Causa
3001	402 Payment Required	La tarjeta fue declinada.
3002	402 Payment Required	La tarjeta ha expirado.
3003	402 Payment Required	La tarjeta no tiene fondos suficientes.
3004	402 Payment Required	La tarjeta ha sido identificada como una tarjeta robada.
3005	402 Payment Required	La tarjeta ha sido identificada como una tarjeta fraudulenta.
3006	412 Precondition Failed	La operación no esta permitida para este cliente o esta transacción.
3008	412 Precondition Failed	La tarjeta no es soportada en transacciones en linea.
3009	402 Payment Required	La tarjeta fue reportada como perdida.
3010	402 Payment Required	El banco ha restringido la tarjeta.
3011	402 Payment Required	El banco ha solicitado que la tarjeta sea retenida. Contacte al banco.
3012	412 Precondition Failed	Se requiere solicitar al banco autorización para realizar este pago.

Cuentas

Código	Error HTTP	Causa
4001	412 Preconditon Failed	La cuenta de Openpay no tiene fondos suficientes.

cURL

PHP

JAVA

cURL

Ejemplo de objeto

{
    "category" : "request",
    "description" : "The customer with id 'm4hqp35pswl02mmc567' does not exist",
    "http_code" : 404,
    "error_code" : 1005,
    "request_id" : "1981cdb8-19cb-4bad-8256-e95d58bc035c",
    "fraud_rules": [
        "Billing <> BIN Country for VISA/MC"
    ]
}

PHP

Ejemplo de objeto

{
    "category" : "request",
    "description" : "The customer with id 'm4hqp35pswl02mmc567' does not exist",
    "http_code" : 404,
    "error_code" : 1005,
    "request_id" : "1981cdb8-19cb-4bad-8256-e95d58bc035c",
    "fraud_rules": [
        "Billing <> BIN Country for VISA/MC"
    ]
}

JAVA

Ejemplo de objeto

{
    "category" : "request",
    "description" : "The customer with id 'm4hqp35pswl02mmc567' does not exist",
    "http_code" : 404,
    "error_code" : 1005,
    "request_id" : "1981cdb8-19cb-4bad-8256-e95d58bc035c",
    "fraud_rules": [
        "Billing <> BIN Country for VISA/MC"
    ]
}

//Para el caso de java, toda operación regresara una instancia de la clase “OpenpayServiceException” la cual contendrá esta información del error.

Ejemplo de objeto

{
    "category" : "request",
    "description" : "The customer with id 'm4hqp35pswl02mmc567' does not exist",
    "http_code" : 404,
    "error_code" : 1005,
    "request_id" : "1981cdb8-19cb-4bad-8256-e95d58bc035c",
    "fraud_rules": [
        "Billing <> BIN Country for VISA/MC"
    ]
}

//Para el caso de C Sharp, toda operación regresará una instancia de la clase “OpenpayException” la cual contendrá esta información del error.

Cargos

Los cargos se pueden realizar a tarjetas y PSE. A cada cargo se le asigna un identificador único en el sistema.

Los cargos a tarjeta puedes hacerlos a una tarjeta guardada usando el id de la tarjeta, usando un token o puedes enviar la información de la tarjeta al momento de la invocación.

Cambios por disposiciones oficiales para la prevención de fraude E-commerce

Toda integración que se realice mediante SDK o peticiones directas al API de Openpay, es de carácter obligatorio enviar el header X-Forwarded-For donde se deberá indicar la IP del dispositivo del cliente. En las pestañas de las diferentes tecnologías ubicadas del lado derecho se encuentra la definición de cómo debe ser enviado.

Con id de tarjeta o token

Este tipo de cargo requiere una tarjeta guardada o que hayas generado un token. Para guardar tarjetas consulta como crear una tarjeta y para usar tokens consulta la sección creación de tokens.

Una vez que tengas una tarjeta guardada o un token usa la propiedad source_id para enviar el identificador.

La propiedad device_session_id deberá ser generada desde el API JavaScript, véase Fraud detection using device data.

Puedes realizar el cargo a la cuenta del comercio o a la cuenta de un cliente.

Sistema antifraude personalizado
Es posible enviar información adicional a la plataforma Openpay para incrementar su base de conocimientos, esto le permitirá aplicar reglas personalizadas de acuerdo al giro del comercio y de manera oportuna, con el propósito de detectar con la mayor efectividad posible los intentos de fraude.

Petición

Propiedad	Descripción
method	*string* (requerido) Debe contener el valor card para indicar que el cargo se hará de una tarjeta.
source_id	*string* (requerido, longitud = 45) ID de la tarjeta guardada o el id del token creado de donde se retirarán los fondos.
amount	*numeric* (requerido) Cantidad del cargo. Debe ser una cantidad mayor a cero.
currency	*string* (requerido) Tipo de moneda del cargo. Por el momento solo se soportan 1 tipo de moneda: Pesos Colombianos(COP).
iva	*string* (requerido) Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.
description	*string* (requerido, longitud = 250) Una descripción asociada al cargo.
order_id	*string* (opcional, longitud = 100) Identificador único del cargo. Debe ser único entre todas las transacciones.
device_session_id	*string* (requerido, longitud = 255) Identificador del dispositivo generado con la herramienta antifraudes
customer	*objeto* (requerido) Información del cliente al que se le realiza el cargo. Se puede ocupar los mismos parámetros usados en la creación de un cliente pero no se creará una cuenta al cliente. Nota: Este parámetro solo se puede utilizar creando el cargo a nivel comercio Si desea crear un cliente y llevar un historial de sus cargos consulte como crear un cliente y realice el cargo a nivel cliente.

Respuesta

Regresa un objeto de transacción con la información del cargo o una respuesta de error.

cURL

PHP

JAVA

cURL

Definición

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Ejemplo de petición con comercio

curl https://sandbox-api.openpay.co/v1/mzdtln3bqtms6o3kck2f/charges \
   -u sk_e562c42a6q384b2ab02cd47d2n301uwk: \
   -H "Content-type: application/json" \
   -H "X-Forwarded-For: 129.18.168.184" \
   -X POST -d '{
   "source_id" : "kdx205scoizh93upqbte",
   "method" : "card",
   "amount" : 716,
   "currency" : "COP",
   "iva" : "10",
   "description" : "Cargo inicial a mi cuenta",
   "order_id" : "oid-12324",
   "device_session_id" : "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f",
   "customer" : {
        "name" : "Cliente Colombia",
        "last_name" : "Vazquez Juarez",
        "phone_number" : "4448936475",
        "email" : "juan.vazquez@empresa.co"
   }
}'

Ejemplo de respuesta

{
    "id": "trbeuhyvmkr3b9jitajp",
    "authorization": "1128731327",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T12:36:56-05:00",
    "operation_date": "2019-08-12T12:36:56-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12330",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T12:36:56-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.81,
        "tax": 3.4896,
        "currency": "COP"
    }
}

PHP

Definición

<?
Comercio
$openpay->charges->create(chargeRequest);

Cliente
$customer = $openpay->customers->get($customerId);
$customer->charges->create(chargeRequest);
?>

Ejemplo de petición con comercio

<?
$openpay = Openpay::getInstance('mzdtln3bqtms6o3kck2f', 'sk_e562c42a6q384b2ab02cd47d2n301uwk', 'CO');
$customer = array(
     'name' => 'Juan',
     'last_name' => 'Vazquez Juarez',
     'phone_number' => '571627926831',
     'email' => 'juan.vazquez@empresa.co');

$chargeRequest = array(
    'method' => 'card',
    'source_id' => 'kqgykn96i7bcs1wwhvgw',
    'amount' => 716,
    'currency' => 'COP',
    'iva' => '10',
    'description' => 'Cargo inicial a mi merchant',
    'order_id' => 'oid-00051',
    'device_session_id' => 'kR1MiQhz2otdIuUlQkbEyitIqVMiI16f',
    'customer' => $customer);

$charge = $openpay->charges->create($chargeRequest);
?>

Ejemplo de respuesta

{
    "id": "trbeuhyvmkr3b9jitajp",
    "authorization": "1128731327",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T12:36:56-05:00",
    "operation_date": "2019-08-12T12:36:56-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12330",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T12:36:56-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.81,
        "tax": 3.4896,
        "currency": "COP"
    }
}

JAVA

Definición

//Cliente
openpayAPI.charges().create(String customerId, CreateCardChargeParams request);

//Comercio
openpayAPI.charges().create(CreateCardChargeParams request);

Ejemplo de petición con comercio

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
CreateCardChargeParams request = new CreateCardChargeParams();
Customer customer = new Customer();
customer.setName("Juan");
customer.setLastName("Vazquez Juarez");
customer.setPhoneNumber("571627926831");
customer.setEmail("juan.vazquez@empresa.co");

request.cardId("kqgykn96i7bcs1wwhvgw"); // =source_id
request.amount(new BigDecimal("716"));
request.currency("COP");
request.iva("10");
request.description("Cargo inicial a mi merchant");
request.orderId("oid-00051");
request.deviceSessionId("kR1MiQhz2otdIuUlQkbEyitIqVMiI16f");
request.setCustomer(customer);

Charge charge = api.charges().create(request);

Ejemplo de respuesta

{
    "id": "trbeuhyvmkr3b9jitajp",
    "authorization": "1128731327",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T12:36:56-05:00",
    "operation_date": "2019-08-12T12:36:56-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12330",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T12:36:56-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.81,
        "tax": 3.4896,
        "currency": "COP"
    }
}

Definición

//Cliente
openpayAPI.ChargeService.Create(string customer_id, ChargeRequest request);

//Comercio
openpayAPI.ChargeService.Create(ChargeRequest request);

Ejemplo de petición con comercio

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");

Customer customer = new Customer();
customer.Name = "Juan";
customer.LastName = "Vazquez Juarez";
customer.PhoneNumber = "571627926831";
customer.Email = "juan.vazquez@empresa.co";

ChargeRequest request = new ChargeRequest();
request.Method = "card";
request.SourceId = "kwkoqpg6fcvfse8k8mg2";
request.Amount = new Decimal(716);
request.Currency = "COP";
request.Iva = "10";
request.Description = "Cargo inicial a mi merchant";
request.OrderId = "oid-00051";
request.DeviceSessionId = "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f";
request.Customer = customer;

Charge charge = api.ChargeService.Create(request);

Ejemplo de respuesta

{
    "id": "trbeuhyvmkr3b9jitajp",
    "authorization": "1128731327",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T12:36:56-05:00",
    "operation_date": "2019-08-12T12:36:56-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12330",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T12:36:56-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.81,
        "tax": 3.4896,
        "currency": "COP"
    }
}

Con redireccionamiento

Este tipo de cargo no requiere una tarjeta guardada o que hayas generado un token.

Petición

Propiedad	Descripción
method	*string* (requerido en card) Debe contener el valor card para indicar que el cargo se hará de una tarjeta.
amount	*numeric* (requerido) Cantidad del cargo. Debe ser una cantidad mayor a cero.
currency	*string* (requerido) Tipo de moneda del cargo. Por el momento solo se soportan 1 tipo de moneda: Pesos Colombianos(COP).
iva	*string* (requerido) Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.
description	*string* (requerido, longitud = 250) Una descripción asociada al cargo.
order_id	*string* (opcional, longitud = 100) Identificador único del cargo. Debe ser único entre todas las transacciones.
customer	*objeto* (requerido) Información del cliente al que se le realiza el cargo. Se puede ocupar los mismos parámetros usados en la creación de un cliente pero no se creará una cuenta al cliente. Nota: Este parámetro solo se puede utilizar creando el cargo a nivel comercio Si desea crear un cliente y llevar un historial de sus cargos consulte como crear un cliente y realice el cargo a nivel cliente.
confirm	*boolean* (requerido en false) El valor `false` indica que se trata de un cargo con terminal virtual.
send_email	*boolean* (opcional) Indica si se desea enviar un email que direccione al formulario de pago de openpay.
redirect_url	*string* (requerido) Indica la url a la que redireccionar despues de una transaccion exitosa en el fomulario de pago de openpay.

Respuesta

Regresa un objeto de transacción con la información del cargo o una respuesta de error.

cURL

PHP

JAVA

cURL

Con redireccionamiento

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Ejemplo de petición con comercio

curl https://sandbox-api.openpay.co/v1/mzdtln3bqtms6o3kck2f/charges \
   -u sk_e562c42a6q384b2ab02cd47d2n301uwk: \
   -H "Content-type: application/json" \
   -X POST -d '{
   "source_id" : "kdx205scoizh93upqbte",
   "method" : "card",
   "amount" : 716,
   "currency" : "COP",
   "iva" : "10",
   "description" : "Cargo inicial a mi cuenta",
   "order_id" : "oid-12324",
   "device_session_id" : "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f",
   "customer" : {
        "name" : "Cliente Colombia",
        "last_name" : "Vazquez Juarez",
        "phone_number" : "4448936475",
        "email" : "juan.vazquez@empresa.co"
   }
}'

Ejemplo de respuesta

{
    "id": "trbeuhyvmkr3b9jitajp",
    "authorization": "1128731327",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T12:36:56-05:00",
    "operation_date": "2019-08-12T12:36:56-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12330",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T12:36:56-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.81,
        "tax": 3.4896,
        "currency": "COP"
    }
}

PHP

Con redireccionamiento

Definición

<?
Comercio
$openpay->charges->create(chargeRequest);

Cliente
$customer = $openpay->customers->get($customerId);
$customer->charges->create(chargeRequest);
?>

Ejemplo de petición con comercio

<?
$openpay = Openpay::getInstance('mzdtln3bqtms6o3kck2f', 'sk_e562c42a6q384b2ab02cd47d2n301uwk', 'CO');
$customer = array(
     'name' => 'Juan',
     'last_name' => 'Vazquez Juarez',
     'phone_number' => '4423456723',
     'email' => 'juan.vazquez@empresa.co');

$chargeRequest = array(
    'method' : 'card',
    'amount' => 716,
    'currency' => 'COP',
    'iva' => '28',
    'description' => 'Cargo terminal virtual a mi merchant',
    'customer' => $customer,
    'send_email' => false,
    'confirm' => false,
    'redirect_url' => '/index.html')
;

$charge = $openpay->charges->create($chargeRequest);
?>

Ejemplo de respuesta


{
    "id": "tro1ezxbfn5c8lvzhfcr",
    "authorization": null,
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "status": "charge_pending",
    "conciliated": false,
    "creation_date": "2019-08-12T12:47:41-05:00",
    "operation_date": "2019-08-12T12:47:41-05:00",
    "description": "Cargo inicial a mi cuenta",
    "error_message": null,
    "order_id": "oid-11153",
    "payment_method": {
        "type": "redirect",
        "url": "https://sandbox-api.openpay.co/v1/mpixehq7z4xupfwoohrm/charges/tro1ezxbfn5c8lvzhfcr/card_capture"
    },
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Juan",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4423456723",
        "address": null,
        "creation_date": "2019-08-12T12:47:41-05:00",
        "external_id": null
    }
}

JAVA

Con redireccionamiento

Definición

//Customer
openpayAPI.charges().create(String customerId, CreateCardChargeParams request);

//Merchant
openpayAPI.charges().create(CreateCardChargeParams request);

Ejemplo de petición con comercio

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
CreateCardChargeParams request = new CreateCardChargeParams();
Customer customer = new Customer();
customer.setName("Juan");
customer.setLastName("Vazquez Juarez");
customer.setPhoneNumber("4423456723");
customer.setEmail("juan.vazquez@empresa.co");

request.amount(new BigDecimal("716.00"));
request.currency("COP");
request.iva("16");
request.description("Cargo inicial a mi merchant");
request.orderId("oid-00051");
request.setCustomer(customer);
request.setSendEmail(false);
request.setConfirm(false);
request.setRedirectUrl("/index.html");

Charge charge = api.charges().create(request);

Ejemplo de respuesta


{
    "id": "tro1ezxbfn5c8lvzhfcr",
    "authorization": null,
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "status": "charge_pending",
    "conciliated": false,
    "creation_date": "2019-08-12T12:47:41-05:00",
    "operation_date": "2019-08-12T12:47:41-05:00",
    "description": "Cargo inicial a mi cuenta",
    "error_message": null,
    "order_id": "oid-11153",
    "payment_method": {
        "type": "redirect",
        "url": "https://sandbox-api.openpay.co/v1/mpixehq7z4xupfwoohrm/charges/tro1ezxbfn5c8lvzhfcr/card_capture"
    },
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Juan",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4423456723",
        "address": null,
        "creation_date": "2019-08-12T12:47:41-05:00",
        "external_id": null
    }
}

Con redireccionamiento

Definición

//Cliente
openpayAPI.ChargeService.Create(string customer_id, ChargeRequest request);

//Comercio
openpayAPI.ChargeService.Create(ChargeRequest request);

Ejemplo de petición con comercio

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
ChargeRequest request = new ChargeRequest();
Customer customer = new Customer();
customer.Name = "Juan";
customer.LastName = "Vazquez Juarez";
customer.PhoneNumber = "4423456723";
customer.Email = "juan.vazquez@empresa.co";

request.Method = "card";
request.Amount = new Decimal(716);
request.Currency = "COP";
request.Iva = "16";
request.Description = "Cargo inicial a mi merchant";
request.OrderId = "oid-00051";
request.Confirm = false;
request.SendEmail = false;
request.RedirectUrl = "/index.html";
request.Customer = customer;

Charge charge = api.ChargeService.Create(request);

Ejemplo de respuesta


{
    "id": "tro1ezxbfn5c8lvzhfcr",
    "authorization": null,
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "status": "charge_pending",
    "conciliated": false,
    "creation_date": "2019-08-12T12:47:41-05:00",
    "operation_date": "2019-08-12T12:47:41-05:00",
    "description": "Cargo inicial a mi cuenta",
    "error_message": null,
    "order_id": "oid-11153",
    "payment_method": {
        "type": "redirect",
        "url": "https://sandbox-api.openpay.co/v1/mpixehq7z4xupfwoohrm/charges/tro1ezxbfn5c8lvzhfcr/card_capture"
    },
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Juan",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4423456723",
        "address": null,
        "creation_date": "2019-08-12T12:47:41-05:00",
        "external_id": null
    }
}

Cargo en tienda

Para un pago en una tienda de conveniencia se debe crear un petición de tipo cargo indicando como método store. Esto generará una respuesta con un número de referencia y una URL a un código de barras, los cuales debes de utilizar para crear un recibo a tu cliente y que con él pueda realizar el pago en una de las tienda de conveniencia aceptadas. El código de barras es de tipo Code 128.

Petición

Propiedad	Descripción
method	*string* (requerido) Debe contener el valor store para indicar que el pago se hará en tienda.
amount	*numeric* (requerido) Cantidad del cargo. Debe ser una cantidad mayor a cero, con hasta dos dígitos decimales.
currency	*string* (requerido) Tipo de moneda del pago. Por el momento solo se soportan 1 tipo de moneda: Pesos Colombianos(COP).
iva	*string* (requerido) Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.
description	*string* (requerido, longitud = 250) Una descripción asociada al cargo.
order_id	*string* (opcional, longitud = 100) Identificador único del cargo. Debe ser único entre todas las transacciones.
due_date	*datetime* (opcional) Fecha de vigencia para hacer el pago en la tienda en formato ISO 8601. Ejemplo (UTC): 2014-08-01T00:50:00Z *Nota:* Del lado del servidor se cambiara a hora central Ejemplo (Central Time): 2014-08-01T11:51:23-05:00
customer	*objeto* (requerido) Información del cliente al que se le realiza el cargo. Se puede ocupar los mismos parámetros usados en la creación de un cliente pero no se creará una cuenta al cliente. Nota: Este parámetro solo se puede utilizar creando el cargo a nivel comercio Si desea crear un cliente y llevar un historial de sus cargos consulte como crear un cliente y realize el cargo a nivel cliente.

Respuesta

Regresa un objeto de transacción con la información del cargo o una respuesta de error. currency | string (requerido)
Moneda usada en la operación

Respuesta

Regresa un objeto de transacción con la información del cargo o una respuesta de error.

cURL

PHP

JAVA

cURL

Cargo en tienda

Definición

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
   "method" : "store",
   "amount" : 100,
   "currency" : "COP",
   "iva" : "10",
   "description" : "Cargo con tienda",
   "order_id" : "oid-00053",
   "due_date" : "2018-05-28T13:45:00"
}'

Ejemplo de respuesta

{
   "id":"trnirkiyobo5qfex55ef",
   "amount":100.00,
   "currency":"COP",
   "iva":"10",
   "authorization":null,
   "method":"store",
   "operation_type":"in",
   "transaction_type":"charge",
   "status":"in_progress",
   "creation_date":"2018-05-26T13:48:25-05:00",
   "operation_date":"2018-05-26T13:48:25-05:00",
   "due_date":"2018-05-28T13:45:00-05:00",
   "description":"Cargo con tienda",
   "error_message":null,
   "order_id":"oid-00053",
   "customer_id":"ag4nktpdzebjiye1tlze",
   "payment_method":{
      "type":"store",
      "reference":"000020TRNIRKIYOBO5QFEX55EF0100009",
      "paybin_reference":"0101990000001065",
      "barcode_url":"https://sandbox-api.openpay.co/barcode/000020TRNIRKIYOBO5QFEX55EF0100009?width=1&height=45&text=false",
      "barcode_paybin_url":"https://sandbox-api.openpay.co/barcode/0101990000001065?width=1&height=45&text=false"
   }
}

PHP

Cargo en tienda

Definición

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

<?
Comercio
$openpay->charges->create(chargeRequest);

Cliente
$customer = $openpay->customers->get(customerId);
$customer->charges->create(chargeRequest;
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab', 'CO');

$chargeRequest = array(
    'method' => 'store',
    'amount' => 100,
    'currency' => 'COP',
    'iva' => '10',
    'description' => 'Cargo con tienda',
    'order_id' => 'oid-00053',
    'due_date' => '2018-05-28T13:45:00');

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$charge = $customer->charges->create($chargeRequest);
?>

Ejemplo de respuesta

{
   "id":"trnirkiyobo5qfex55ef",
   "amount":100.00,
   "currency":"COP",
   "iva":"10",
   "authorization":null,
   "method":"store",
   "operation_type":"in",
   "transaction_type":"charge",
   "status":"in_progress",
   "creation_date":"2018-05-26T13:48:25-05:00",
   "operation_date":"2018-05-26T13:48:25-05:00",
   "due_date":"2018-05-28T13:45:00-05:00",
   "description":"Cargo con tienda",
   "error_message":null,
   "order_id":"oid-00053",
   "customer_id":"ag4nktpdzebjiye1tlze",
   "payment_method":{
      "type":"store",
      "reference":"000020TRNIRKIYOBO5QFEX55EF0100009",
      "paybin_reference":"0101990000001065",
      "barcode_url":"https://sandbox-api.openpay.co/barcode/000020TRNIRKIYOBO5QFEX55EF0100009?width=1&height=45&text=false",
      "barcode_paybin_url":"https://sandbox-api.openpay.co/barcode/0101990000001065?width=1&height=45&text=false"
   }
}

JAVA

Cargo en tienda

Definición

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

//Cliente
openpayAPI.charges().create(String customerId, CreateStoreChargeParams request);

//Comercio
openpayAPI.charges().create(CreateStoreChargeParams request);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Calendar dueDate = Calendar.getInstance();
dueDate.set(2018, 5, 28, 13, 45, 0);
CreateStoreChargeParams request = new CreateStoreChargeParams();
request.amount(new BigDecimal("100.00"));
request.currency("COP");
request.iva("10");
request.description("Cargo con tienda");
request.orderId("oid-00053"
request.dueDate(dueDate.getTime());

Charge charge = api.charges().create("ag4nktpdzebjiye1tlze", request);

Ejemplo de respuesta

{
   "id":"trnirkiyobo5qfex55ef",
   "amount":100.00,
   "currency":"COP",
   "iva":"10",
   "authorization":null,
   "method":"store",
   "operation_type":"in",
   "transaction_type":"charge",
   "status":"in_progress",
   "creation_date":"2018-05-26T13:48:25-05:00",
   "operation_date":"2018-05-26T13:48:25-05:00",
   "due_date":"2018-05-28T13:45:00-05:00",
   "description":"Cargo con tienda",
   "error_message":null,
   "order_id":"oid-00053",
   "customer_id":"ag4nktpdzebjiye1tlze",
   "payment_method":{
      "type":"store",
      "reference":"000020TRNIRKIYOBO5QFEX55EF0100009",
      "paybin_reference":"0101990000001065",
      "barcode_url":"https://sandbox-api.openpay.co/barcode/000020TRNIRKIYOBO5QFEX55EF0100009?width=1&height=45&text=false",
      "barcode_paybin_url":"https://sandbox-api.openpay.co/barcode/0101990000001065?width=1&height=45&text=false"
   }
}

Cargo en tienda

Definición

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

//Cliente
openpayAPI.ChargeService.Create(string customer_id, ChargeRequest request);

//Comercio
openpayAPI.ChargeService.Create(ChargeRequest request);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
ChargeRequest request = new ChargeRequest();
request.Method = "store";
request.Amount = new Decimal(100);
request.Currency = "COP";
request.Iva = "10";
request.Description = "Cargo con tienda";
request.OrderId = "oid-00053";
request.DueDate = new DateTime(2018, 5, 28, 13, 45, 0);

Charge charge = api.ChargeService.Create("ag4nktpdzebjiye1tlze", request);

Ejemplo de respuesta

{
   "id":"trnirkiyobo5qfex55ef",
   "amount":100.00,
   "currency":"COP",
   "iva":"10",
   "authorization":null,
   "method":"store",
   "operation_type":"in",
   "transaction_type":"charge",
   "status":"in_progress",
   "creation_date":"2018-05-26T13:48:25-05:00",
   "operation_date":"2018-05-26T13:48:25-05:00",
   "due_date":"2018-05-28T13:45:00-05:00",
   "description":"Cargo con tienda",
   "error_message":null,
   "order_id":"oid-00053",
   "customer_id":"ag4nktpdzebjiye1tlze",
   "payment_method":{
      "type":"store",
      "reference":"000020TRNIRKIYOBO5QFEX55EF0100009",
      "paybin_reference":"0101990000001065",
      "barcode_url":"https://sandbox-api.openpay.co/barcode/000020TRNIRKIYOBO5QFEX55EF0100009?width=1&height=45&text=false",
      "barcode_paybin_url":"https://sandbox-api.openpay.co/barcode/0101990000001065?width=1&height=45&text=false"
   }
}

Devolver un cargo

Si deseas realizar una devolución de un cargo hecho a tarjeta puedes ocupar este método. El monto a devolver será por el total del cargo o un monto menor. Ten en cuenta que la devolución puede tardar en aparecer en el estado de cuenta de tu cliente de 1 a 3 días hábiles.

Nota: Solo se pueden hacer devoluciones de cargos a tarjeta.

Petición

Propiedad	Descripción
description	*string* (opcional, longitud = 250) Texto libre para describir motivo de la devolución.
amount	*numeric* (opcional) Cantidad a reembolsar. Debe ser una cantidad mayor a cero y menor o igual al cargo original.

Respuesta

Regresa un objeto de transacción con la información del cargo o una respuesta de error.

cURL

PHP

JAVA

cURL

Devolver un cargo

Definición

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges/{TRANSACTION_ID}/refund

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges/{TRANSACTION_ID}/refund

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges/tr6cxbcefzatd10guvvw/refund \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
   "description" : "devolución",
   "amount" : 100.00
} '

Ejemplo de respuesta

{
   "id":"tr6cxbcefzatd10guvvw",
   "amount":100.00,
   "currency":"COP",
   "iva":"10",
   "authorization":"801585",
   "method":"card",
   "operation_type":"in",
   "transaction_type":"charge",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"002"
   },
   "status":"completed",
   "refund":{
      "id":"trcbsmjkroqmjobxqhpb",
      "amount":100.00,
      "authorization":"801585",
      "method":"card",
      "operation_type":"out",
      "transaction_type":"refund",
      "status":"completed",
      "currency":"COP",
      "creation_date":"2018-05-26T13:56:21-05:00",
      "operation_date":"2018-05-26T13:56:21-05:00",
      "description":"devolucion",
      "error_message":null,
      "order_id":null,
      "customer_id":"ag4nktpdzebjiye1tlze"
   },
   "creation_date":"2018-05-26T11:56:25-05:00",
   "operation_date":"2018-05-26T11:56:25-05:00",
   "description":"Cargo inicial a mi cuenta",
   "error_message":null,
   "order_id":"oid-00052",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

PHP

Devolver un cargo

Definición

<?
Comercio
$charge = $openpay->charges->get(transactionId);
$charge->refund(refundData);

Cliente
$customer = $openpay->customers->get(customerId);
$charge = $customer->charges->get(transactionId);
$charge->refund(refundData);
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab', 'CO');

$refundData = array(
    'description' => 'devolución',
    'amount' => 100);

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$charge = $customer->charges->get('tr6cxbcefzatd10guvvw');
$charge->refund($refundData);
?>

Ejemplo de respuesta

{
   "id":"tr6cxbcefzatd10guvvw",
   "amount":100.00,
   "currency":"COP",
   "iva":"10",
   "authorization":"801585",
   "method":"card",
   "operation_type":"in",
   "transaction_type":"charge",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"002"
   },
   "status":"completed",
   "refund":{
      "id":"trcbsmjkroqmjobxqhpb",
      "amount":100.00,
      "authorization":"801585",
      "method":"card",
      "operation_type":"out",
      "transaction_type":"refund",
      "status":"completed",
      "currency":"COP",
      "creation_date":"2018-05-26T13:56:21-05:00",
      "operation_date":"2018-05-26T13:56:21-05:00",
      "description":"devolucion",
      "error_message":null,
      "order_id":null,
      "customer_id":"ag4nktpdzebjiye1tlze"
   },
   "creation_date":"2018-05-26T11:56:25-05:00",
   "operation_date":"2018-05-26T11:56:25-05:00",
   "description":"Cargo inicial a mi cuenta",
   "error_message":null,
   "order_id":"oid-00052",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

JAVA

Devolver un cargo

Definición

//Cliente
openpayAPI.charges().refund(String customerId, RefundParams request);

//Comercio
openpayAPI.charges().refund(RefundParams request);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
RefundParams request = new RefundParams();
request.chargeId("tr6cxbcefzatd10guvvw");
request.description("Monto de cargo devuelto");
request.amount(new BigDecimal("100.00"));

Charge charge = api.charges().refund("ag4nktpdzebjiye1tlze", request);

Ejemplo de respuesta

{
   "id":"tr6cxbcefzatd10guvvw",
   "amount":100.00,
   "currency":"COP",
   "iva":"10",
   "authorization":"801585",
   "method":"card",
   "operation_type":"in",
   "transaction_type":"charge",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"002"
   },
   "status":"completed",
   "refund":{
      "id":"trcbsmjkroqmjobxqhpb",
      "amount":100.00,
      "authorization":"801585",
      "method":"card",
      "operation_type":"out",
      "transaction_type":"refund",
      "status":"completed",
      "currency":"COP",
      "creation_date":"2018-05-26T13:56:21-05:00",
      "operation_date":"2018-05-26T13:56:21-05:00",
      "description":"devolucion",
      "error_message":null,
      "order_id":null,
      "customer_id":"ag4nktpdzebjiye1tlze"
   },
   "creation_date":"2018-05-26T11:56:25-05:00",
   "operation_date":"2018-05-26T11:56:25-05:00",
   "description":"Cargo inicial a mi cuenta",
   "error_message":null,
   "order_id":"oid-00052",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Devolver un cargo

Definición

//Cliente
openpayAPI.ChargeService.Refund(string customer_id, string transaction_id, string description);

//Comercio
openpayAPI.ChargeService.Refund(string transaction_id, string description);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Charge charge = api.ChargeService.Refund("ag4nktpdzebjiye1tlze", "tryqihxac3msedn4yxed", "Monto de cargo devuelto", , new Decimal(100.00));

Ejemplo de respuesta

{
   "id":"tr6cxbcefzatd10guvvw",
   "amount":100.00,
   "currency":"COP",
   "iva":"10",
   "authorization":"801585",
   "method":"card",
   "operation_type":"in",
   "transaction_type":"charge",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"002"
   },
   "status":"completed",
   "refund":{
      "id":"trcbsmjkroqmjobxqhpb",
      "amount":100.00,
      "authorization":"801585",
      "method":"card",
      "operation_type":"out",
      "transaction_type":"refund",
      "status":"completed",
      "currency":"COP",
      "creation_date":"2018-05-26T13:56:21-05:00",
      "operation_date":"2018-05-26T13:56:21-05:00",
      "description":"devolucion",
      "error_message":null,
      "order_id":null,
      "customer_id":"ag4nktpdzebjiye1tlze"
   },
   "creation_date":"2018-05-26T11:56:25-05:00",
   "operation_date":"2018-05-26T11:56:25-05:00",
   "description":"Cargo inicial a mi cuenta",
   "error_message":null,
   "order_id":"oid-00052",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Obtener un cargo

Regresa la información de un cargo generado en cualquier momento solo con conocer el id de cargo.

Petición

Propiedad	Descripción
transaction_id	string (requerido, longitud = 45) Identificador del cargo a consultar.

Respuesta

Regresa un objeto de transacción con la información del cargo o una respuesta de error.

cURL

PHP

JAVA

cURL

Obtener un cargo

Definición

Comercio
GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges/{TRANSACTION_ID}

Comercio
GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges/{TRANSACTION_ID}

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln3bqtms6o3kck2f/customers/ag9nkpvdzebjiye5tlzi/charges/tr6cxbcefzatd10guvvw \
   -u sk_e562c42a6q384b2ab02cd47d2n301uwk:

Ejemplo de respuesta

{
    "id": "trsc2di0dymydqkm5ieo",
    "authorization": "194883321",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T13:02:18-05:00",
    "operation_date": "2019-08-12T13:02:18-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12331",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T13:02:18-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.8100,
        "tax": 3.4896,
        "currency": "COP"
    }
}

PHP

Obtener un cargo

Definición

<?
Comercio
$charge = $openpay->charges->get(transactionId);

Cliente
$customer = $openpay->customers->get(customerId);
$charge = $customer->charges->get(transactionId);
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('mzdtln3bqtms6o3kck2f', 'sk_e562c42a6q384b2ab02cd47d2n301uwk', 'CO');

$customer = $openpay->customers->get('ag9nkpvdzebjiye5tlzi');
$charge = $customer->charges->get('tr6cxbcefzatd10guvvw');
?>

Ejemplo de respuesta

{
    "id": "trsc2di0dymydqkm5ieo",
    "authorization": "194883321",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T13:02:18-05:00",
    "operation_date": "2019-08-12T13:02:18-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12331",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T13:02:18-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.8100,
        "tax": 3.4896,
        "currency": "COP"
    }
}

JAVA

Obtener un cargo

Definición

//Cliente
openpayAPI.charges().get(String customerId, String transactionId);

//Comercio
openpayAPI.charges().get(String transactionId);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Charge charge = api.charges().get("ag9nkpvdzebjiye5tlzi", "tr6cxbcefzatd10guvvw");

Ejemplo de respuesta

{
    "id": "trsc2di0dymydqkm5ieo",
    "authorization": "194883321",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T13:02:18-05:00",
    "operation_date": "2019-08-12T13:02:18-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12331",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T13:02:18-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.8100,
        "tax": 3.4896,
        "currency": "COP"
    }
}

Obtener un cargo

Definición

//Cliente
openpayAPI.ChargeService.Get(string customer_id, string transaction_id);

//Comercio
openpayAPI.ChargeService.Get(string transaction_id);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Charge charge = api.ChargeService.Get("ag9nkpvdzebjiye5tlzi", "tryqihxac3msedn4yxed");

Ejemplo de respuesta

{
    "id": "trsc2di0dymydqkm5ieo",
    "authorization": "194883321",
    "operation_type": "in",
    "method": "card",
    "transaction_type": "charge",
    "card": {
        "id": "kdx205scoizh93upqbte",
        "type": "credit",
        "brand": "diners",
        "address": null,
        "card_number": "367284XXXX3333",
        "holder_name": "DinnersClub",
        "expiration_year": "21",
        "expiration_month": "07",
        "allows_charges": true,
        "creation_date": "2019-08-09T13:35:48-05:00",
        "bank_name": "BANCO DE BOGOTÁ",
        "bank_code": "000"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2019-08-12T13:02:18-05:00",
    "operation_date": "2019-08-12T13:02:18-05:00",
    "description": "Ejemplo cargo",
    "error_message": null,
    "order_id": "oid-12331",
    "amount": 716,
    "currency": "COP",
    "iva": "10",
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2019-08-12T13:02:18-05:00",
        "external_id": null
    },
    "fee": {
        "amount": 21.8100,
        "tax": 3.4896,
        "currency": "COP"
    }
}

Listado de cargos

Obtiene un listado de los cargos realizados por comercio o cliente.

Petición

Puede realizar una búsqueda utilizando los siguiente parámetros como filtros.

Propiedad	Descripción
order_id	*string* Identificador único de la orden generado por el comercio y asociado a la transacción mediante el campo order_id de la petición del cargo.
creation	*date* Igual a la fecha de creación. Formato yyyy-mm-dd
creation[gte]	*date* Mayor a la fecha de creación. Formato yyyy-mm-dd
creation[lte]	*date* Menor a la fecha de creación. Formato yyyy-mm-dd
offset	*numeric* Número de registros a omitir al inicio, por defecto 0.
limit	*numeric* Número de registros que se requieren, por defecto 10.
amount	*numeric* Igual al monto.
amount[gte]	*numeric* Mayor o igual al monto.
amount[lte]	*numeric* Menor o igual al monto.
status	*TransactionStatus* Estado de la transacción (IN_PROGRESS,COMPLETED,REFUNDED, CHARGEBACK_PENDING,CHARGEBACK_ACCEPTED,CHARGEBACK_ADJUSTMENT, CHARGE_PENDING,CANCELLED,FAILED).

Respuesta

Regresa un arreglo de objetos de transacción de los cargos en orden descendente por fecha de creación.

cURL

PHP

JAVA

cURL

Listado de cargos

Definición

Comercio
GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/charges

Comercio
GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Ejemplo de petición con cliente

curl -g "https://sandbox-api.openpay.co/v1/mzdtln3bqtms6o3kck2f/customers/ag9nkpvdzebjiye5tlzi/charges?creation[gte]=2018-11-01&limit=2" \
   -u sk_e562c42a6q384b2ab02cd47d2n301uwk:

Ejemplo de respuesta

[
    {
        "id": "trsc2di0dymydqkm5ieo",
        "authorization": "194883321",
        "operation_type": "in",
        "method": "card",
        "transaction_type": "charge",
        "card": {
            "id": "kdx205scoizh93upqbte",
            "type": "credit",
            "brand": "diners",
            "address": null,
            "card_number": "367284XXXX3333",
            "holder_name": "DinnersClub",
            "expiration_year": "21",
            "expiration_month": "07",
            "allows_charges": true,
            "creation_date": "2019-08-09T13:35:48-05:00",
            "bank_name": "BANCO DE BOGOTÁ",
            "bank_code": "000"
        },
        "status": "completed",
        "conciliated": true,
        "creation_date": "2019-08-12T13:02:18-05:00",
        "operation_date": "2019-08-12T13:02:18-05:00",
        "description": "Ejemplo cargo",
        "error_message": null,
        "order_id": "oid-12331",
        "amount": 716,
        "currency": "COP",
        "iva": "10",
        "customer": {
            "name": "Cliente Colombia",
            "last_name": "Vazquez Juarez",
            "email": "juan.vazquez@empresa.co",
            "phone_number": "4448936475",
            "address": null,
            "creation_date": "2019-08-12T13:02:18-05:00",
            "external_id": null
        },
        "fee": {
          "amount": 21.8100,
          "tax": 3.4896,
          "currency": "COP"
        }
    }

]

PHP

Listado de cargos

Definición

<?
Comercio
$chargeList = $openpay->charges->getList(searchParams);

Cliente
$customer = $openpay->customers->get(customerId);
$chargeList = $customer->charges->getList(searchParams);
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('mzdtln3bqtms6o3kck2f', 'sk_e562c42a6q384b2ab02cd47d2n301uwk', 'CO');

$searchParams = array(
    'creation[gte]' => '2018-11-01',
    'creation[lte]' => '2019-11-01',
    'offset' => 0,
    'limit' => 2);

$customer = $openpay->customers->get('ag9nkpvdzebjiye5tlzi');
$chargeList = $customer->charges->getList($searchParams);
?>

Ejemplo de respuesta

[
    {
        "id": "trsc2di0dymydqkm5ieo",
        "authorization": "194883321",
        "operation_type": "in",
        "method": "card",
        "transaction_type": "charge",
        "card": {
            "id": "kdx205scoizh93upqbte",
            "type": "credit",
            "brand": "diners",
            "address": null,
            "card_number": "367284XXXX3333",
            "holder_name": "DinnersClub",
            "expiration_year": "21",
            "expiration_month": "07",
            "allows_charges": true,
            "creation_date": "2019-08-09T13:35:48-05:00",
            "bank_name": "BANCO DE BOGOTÁ",
            "bank_code": "000"
        },
        "status": "completed",
        "conciliated": true,
        "creation_date": "2019-08-12T13:02:18-05:00",
        "operation_date": "2019-08-12T13:02:18-05:00",
        "description": "Ejemplo cargo",
        "error_message": null,
        "order_id": "oid-12331",
        "amount": 716,
        "currency": "COP",
        "iva": "10",
        "customer": {
            "name": "Cliente Colombia",
            "last_name": "Vazquez Juarez",
            "email": "juan.vazquez@empresa.co",
            "phone_number": "4448936475",
            "address": null,
            "creation_date": "2019-08-12T13:02:18-05:00",
            "external_id": null
        },
        "fee": {
          "amount": 21.8100,
          "tax": 3.4896,
          "currency": "COP"
        }
    }

]

JAVA

Listado de cargos

Definición

//Cliente
openpayAPI.charges().list(String customerId, SearchParams request);

//Comercio
openpayAPI.charges().list(SearchParams request);

Ejemplo de petición con cliente

final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2019, 5, 1, 0, 0, 0);
dateLte.set(2019, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);
request.amount(new BigDecimal("716"));

List<Charge> charges = api.charges().list("ag9nkpvdzebjiye5tlzi", request);

Ejemplo de respuesta

[
    {
        "id": "trsc2di0dymydqkm5ieo",
        "authorization": "194883321",
        "operation_type": "in",
        "method": "card",
        "transaction_type": "charge",
        "card": {
            "id": "kdx205scoizh93upqbte",
            "type": "credit",
            "brand": "diners",
            "address": null,
            "card_number": "367284XXXX3333",
            "holder_name": "DinnersClub",
            "expiration_year": "21",
            "expiration_month": "07",
            "allows_charges": true,
            "creation_date": "2019-08-09T13:35:48-05:00",
            "bank_name": "BANCO DE BOGOTÁ",
            "bank_code": "000"
        },
        "status": "completed",
        "conciliated": true,
        "creation_date": "2019-08-12T13:02:18-05:00",
        "operation_date": "2019-08-12T13:02:18-05:00",
        "description": "Ejemplo cargo",
        "error_message": null,
        "order_id": "oid-12331",
        "amount": 716,
        "currency": "COP",
        "iva": "10",
        "customer": {
            "name": "Cliente Colombia",
            "last_name": "Vazquez Juarez",
            "email": "juan.vazquez@empresa.co",
            "phone_number": "4448936475",
            "address": null,
            "creation_date": "2019-08-12T13:02:18-05:00",
            "external_id": null
        },
        "fee": {
          "amount": 21.8100,
          "tax": 3.4896,
          "currency": "COP"
        }
    }

]

Listado de cargos

Definición

//Cliente
openpayAPI.ChargeService.List(string customer_id, SearchParams request = null);

//Comercio
openpayAPI.ChargeService.List(SearchParams request = null);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2019, 5, 1);
request.CreationLte = new DateTime(2019, 5, 15);
request.Offset = 0;
request.Limit = 100;
request.Amount = new Decimal(716);

List<Charge> charges= openpayAPI.ChargeService.List("ag9nkpvdzebjiye5tlzi", request);

Ejemplo de respuesta

[
    {
        "id": "trsc2di0dymydqkm5ieo",
        "authorization": "194883321",
        "operation_type": "in",
        "method": "card",
        "transaction_type": "charge",
        "card": {
            "id": "kdx205scoizh93upqbte",
            "type": "credit",
            "brand": "diners",
            "address": null,
            "card_number": "367284XXXX3333",
            "holder_name": "DinnersClub",
            "expiration_year": "21",
            "expiration_month": "07",
            "allows_charges": true,
            "creation_date": "2019-08-09T13:35:48-05:00",
            "bank_name": "BANCO DE BOGOTÁ",
            "bank_code": "000"
        },
        "status": "completed",
        "conciliated": true,
        "creation_date": "2019-08-12T13:02:18-05:00",
        "operation_date": "2019-08-12T13:02:18-05:00",
        "description": "Ejemplo cargo",
        "error_message": null,
        "order_id": "oid-12331",
        "amount": 716,
        "currency": "COP",
        "iva": "10",
        "customer": {
            "name": "Cliente Colombia",
            "last_name": "Vazquez Juarez",
            "email": "juan.vazquez@empresa.co",
            "phone_number": "4448936475",
            "address": null,
            "creation_date": "2019-08-12T13:02:18-05:00",
            "external_id": null
        },
        "fee": {
          "amount": 21.8100,
          "tax": 3.4896,
          "currency": "COP"
        }
    }

]

PSE

Los cargos a cuentas de banco se pueden realizar por medio de PSE. Al crear un pago PSE se genera una url para continuar el flujo de pago.

Se requiere la información de un cliente, o puede usarse el id de un cliente existente.

Con id de cliente existente

En la respuesta qué contiene el campo url en el payment_method se continúa el flujo para realizar el pago PSE.

Para utilizar esta característica es necesario enviar como parte del contenido, la propiedad metadata, el cual contendrá un listado de campos personalizados de antrifraude, con la información propia del comercio que se desea tomar en cuenta al momento de validar y aplicar un pago. Póngase en contacto con el departamento de soporte de Openpay para habilitar esta funcion.

Petición

amountnumeric (requerido) Cantidad del cargo. Debe ser una cantidad con valor entero mayor a cero.

Propiedad	Descripción
method	*string* (requerido) Debe contener el valor bank_account para indicar que el método de pago es PSE.
currency	*string* (requerido) Tipo de moneda del pago. Por el momento solo se soportan 1 tipo de moneda: Pesos Colombianos(COP).
iva	*string* (requerido) Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.
description	*string* (requerido, longitud = 250) Una descripción asociada al pago.
order_id	*string* (opcional, longitud = 100) Identificador único del pago. Debe ser único entre todos los pagos.
redirect_url	*string* (requerido) Informa el sitio web al que el cliente será redirigido al finalizar el pago.
metadata	*list(key, value)* (opcional) Listado de campos personalizados de antifraude, estos campos deben de apegarse a las reglas para creación de campos personalizados de antifraude

Respuesta

Regresa una url con la información para continuar el pago PSE o una respuesta de error.

cURL

PHP

JAVA

cURL

Con id de cliente existente

Definición

POST https://sandbox-api.openpay.co/v1/{{MERCHANT_ID}}/customers/{{CUSTOMER_ID}}/charges

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mr0w3azn2utpnldvgxkk/customers/ajazz9nirkarzbdd1nl7/charges \
   -u sk_71ed83f6dcf84bfbb5847fea6b98bbdb: \
   -H "Content-type: application/json" \
   -X POST -d '{
   "method" : "bank_account",
   "amount" : 10000,
   "currency" : "COP",
   "description" : "Cargo inicial a mi cuenta",
   "order_id" : "oid-12345",
   "iva" : "1900",
   "redirect_url":"https://www.openpay.co/"
}'

Ejemplo de respuesta

{
    "id": "tr612azuencuooob8uiv",
    "authorization": null,
    "operation_type": "in",
    "transaction_type": "charge",
    "status": "in_progress",
    "conciliated": false,
    "iva": "1900",
    "creation_date": "2020-06-29T14:05:00-05:00",
    "operation_date": "2020-06-29T14:05:00-05:00",
    "description": "Cargo inicial a mi cuenta",
    "error_message": null,
    "order_id": "oid-12345",
    "customer_id": "ajazz9nirkarzbdd1nl7",
    "due_date": "2020-06-29T16:25:00-05:00",
    "amount": 10000.00,
    "payment_method": {
        "type": "redirect",
        "url": "https://sandbox-api.openpay.co/v1/mr0w3azn2utpnldvgxkk/charges/tr612azuencuooob8uiv/pse_capture"
    },
    "currency": "COP",
    "method": "bank_account"
}

PHP

Con id de cliente existente

Definición

<?
Comercio
$openpay->pses->create($pseRequest);

Cliente
$customer = $openpay->customers->get($customerId);
$customer->pses->create($pseRequest);
?>

Ejemplo de petición con comercio

<?
$openpay = Openpay::getInstance('mzdtln3bqtms6o3kck2f', 'sk_e562c42a6q384b2ab02cd47d2n301uwk', 'CO');
$customer = array(
    'name' => 'Pedro',
    'last_name' => 'Gutierrez',
    'email' => 'pedro.gutierrez@company.co',
    'phone_number' => '571983873875',
    'requires_account' => false,
    'customer_address' => array(
        'department' => 'Medellín',
        'city' => 'Antioquia',
        'additional' => 'Avenida 7r bis #144-28 Apartamento 423'
    )
);

$pseRequest = array(
    'country' => 'COL',
    'amount' => 10000,
    'currency' => 'COP',
    'description' => 'pago pse',
    'order_id' => 'oid-12524',
    'iva' => '190',
    'customer' => $customer
);

$pse = $openpay->pses->create($pseRequest);
?>

Ejemplo de respuesta

{
    "orderId":"oid-12524",
    "redirect_url":"https://sandbox-api.openpay.mx/v1/maonhzpqm8xp2ydssovf/customers/ah8tdi7gr9zll6ejijuu/checkouts/ckqtz7smmjffvc4jgfko/pse"
}

JAVA

Con id de cliente existente

Definición

Ejemplo de petición con comercio

Ejemplo de respuesta

{
    "orderId":"oid-12524",
    "redirect_url":"https://sandbox-api.openpay.mx/v1/maonhzpqm8xp2ydssovf/customers/ah8tdi7gr9zll6ejijuu/checkouts/ckqtz7smmjffvc4jgfko/pse"
}

Con id de cliente existente

Definición

//Cliente
openpayAPI.PseService.Create(string customer_id, PseRequest request);

//Comercio
openpayAPI.PseService.Create(PseRequest request);

Ejemplo de petición con comercio

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");

Customer customer = new Customer();
customer.Name = "Juan";
customer.LastName = "Vazquez Perez";
customer.PhoneNumber = "571627926831";
customer.Email = "juan.vazquez@empresa.co";

Address address = new Address();
address.Department = "Medellín";
address.City = "Antioquia";
address.Additional = "Avenida 18e bis #17-28 Apartamento 451";

customer.Address = address;

PseRequest request = new PseRequest();
request.Customer = customer;
request.Country = "COL";
request.Description = "Pago PSE";
request.Amount = 10000;
request.Iva = "190";
request.Currency = "COP";
request.OrderId = "oid-00051";

Pse pse = openpayAPI.PseService.Create(request);

Ejemplo de respuesta

{
    "orderId":"oid-12524",
    "redirect_url":"https://sandbox-api.openpay.mx/v1/maonhzpqm8xp2ydssovf/customers/ah8tdi7gr9zll6ejijuu/checkouts/ckqtz7smmjffvc4jgfko/pse"
}

Con nuevo cliente

En la respuesta qué contiene el campo url en el payment_method se continúa el flujo para realizar el pago PSE.

Petición

Propiedad	Descripción
method	*string* (requerido) Debe contener el valor bank_account para indicar que el método es PSE.
amount	*numeric* (requerido) Cantidad del cargo. Debe ser una cantidad con valor entero mayor a cero.
currency	*string* (requerido) Tipo de moneda del pago. Por el momento solo se soportan 1 tipo de moneda: Pesos Colombianos(COP).
iva	*string* (requerido) Debe contener el valor de IVA, es campo solo informativo, no tiene ningún efecto sobre el campo amount.
description	*string* (requerido, longitud = 250) Una descripción asociada al pago.
order_id	*string* (opcional, longitud = 100) Identificador único del pago. Debe ser único entre todos los pagos.
customer	*objeto* (requerido) Información del cliente al que se le realiza el pago. Se puede ocupar los mismos parámetros usados en la creación de un cliente pero no se creará una cuenta al cliente.Nota: Este parámetro solo se puede utilizar creando el pago a nivel comercio Si desea crear un cliente y llevar un historial de sus pagos consulte como crear un cliente y realice el pago a nivel cliente.
redirect_url	*string* (requerido) Informa el sitio web al que el cliente será redirigido al finalizar el pago.
metadata	*list(key, value)* (opcional) Listado de campos personalizados de antifraude, estos campos deben de apegarse a las reglas para creación de campos personalizados de antifraude

Respuesta

Regresa una url con la información para continuar el pago PSE o una respuesta de error.

cURL

PHP

JAVA

cURL

Con nuevo cliente

Definición

POST https://sandbox-api.openpay.co/v1/{{MERCHANT_ID}}/charges

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mr0w3azn2utpnldvgxkk/charges \
   -u sk_71ed83f6dcf84bfbb5847fea6b98bbdb: \
   -H "Content-type: application/json" \
   -X POST -d '{
   "method" : "bank_account",
   "amount" : 10000,
   "currency" : "COP",
   "description" : "Cargo inicial a mi cuenta",
   "order_id" : "oid-12345",
   "iva" : "1900",
   "redirect_url":"https://www.openpay.co/",
   "customer" : {
        "name" : "Cliente Colombia",
        "last_name" : "Vazquez Juarez",
        "email" : "juan.vazquez@empresa.co",
        "phone_number" : "4448936475",
        "requires_account" : false,
        "customer_address" : {
            "department" : "Medellín",
            "city" : "Antioquía",
            "additional" : "Avenida 7m bis #174-25 Apartamento 637"
        }
   }
}'

Ejemplo de respuesta

{
    "id": "trpfgkjvusju7u0tssmk",
    "authorization": null,
    "operation_type": "in",
    "transaction_type": "charge",
    "status": "in_progress",
    "conciliated": false,
    "iva": "1900",
    "creation_date": "2020-06-29T13:27:58-05:00",
    "operation_date": "2020-06-29T13:27:58-05:00",
    "description": "Cargo inicial a mi cuenta",
    "error_message": null,
    "order_id": "oid-12345",
    "due_date": "2020-06-29T13:47:58-05:00",
    "payment_method": {
        "type": "redirect",
        "url": "https://sandbox-api.openpay.co/v1/mr0w3azn2utpnldvgxkk/charges/trpfgkjvusju7u0tssmk/pse_capture"
    },
    "currency": "COP",
    "amount": 10000.00,
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2020-06-29T13:27:58-05:00",
        "external_id": null,
        "customer_address": {
            "department": "Medellín",
            "city": "Antioquía",
            "additional": "Avenida 7m bis #174-25 Apartamento 637",
            "country": "CO"
        },
        "clabe": null
    },
    "method": "bank_account"
}

PHP

Con nuevo cliente

Definición

<?
Comercio
$openpay->pses->create($pseRequest);

Cliente
$customer = $openpay->customers->get($customerId);
$customer->pses->create($pseRequest);
?>

Ejemplo de petición con comercio

<?
$openpay = Openpay::getInstance('mzdtln3bqtms6o3kck2f', 'sk_e562c42a6q384b2ab02cd47d2n301uwk', 'CO');
$customer = array(
    'name' => 'Pedro',
    'last_name' => 'Gutierrez',
    'email' => 'pedro.gutierrez@company.co',
    'phone_number' => '571983873875',
    'requires_account' => false,
    'customer_address' => array(
        'department' => 'Medellín',
        'city' => 'Antioquia',
        'additional' => 'Avenida 7r bis #144-28 Apartamento 423'
    )
);

$pseRequest = array(
    'country' => 'COL',
    'amount' => 10000,
    'currency' => 'COP',
    'description' => 'pago pse',
    'order_id' => 'oid-12524',
    'iva' => '190',
    'customer' => $customer
);

$pse = $openpay->pses->create($pseRequest);
?>

Ejemplo de respuesta

{
    "orderId":"oid-12524",
    "redirect_url":"https://sandbox-api.openpay.mx/v1/maonhzpqm8xp2ydssovf/customers/ah8tdi7gr9zll6ejijuu/checkouts/ckqtz7smmjffvc4jgfko/pse"
}

JAVA

Con nuevo cliente

Definición

Ejemplo de petición con comercio

Ejemplo de respuesta

{
    "orderId":"oid-12524",
    "redirect_url":"https://sandbox-api.openpay.mx/v1/maonhzpqm8xp2ydssovf/customers/ah8tdi7gr9zll6ejijuu/checkouts/ckqtz7smmjffvc4jgfko/pse"
}

Con nuevo cliente

Definición

//Cliente
openpayAPI.PseService.Create(string customer_id, PseRequest request);

//Comercio
openpayAPI.PseService.Create(PseRequest request);

Ejemplo de petición con comercio

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");

Customer customer = new Customer();
customer.Name = "Juan";
customer.LastName = "Vazquez Perez";
customer.PhoneNumber = "571627926831";
customer.Email = "juan.vazquez@empresa.co";

Address address = new Address();
address.Department = "Medellín";
address.City = "Antioquia";
address.Additional = "Avenida 18e bis #17-28 Apartamento 451";

customer.Address = address;

PseRequest request = new PseRequest();
request.Customer = customer;
request.Country = "COL";
request.Description = "Pago PSE";
request.Amount = 10000;
request.Iva = "190";
request.Currency = "COP";
request.OrderId = "oid-00051";

Pse pse = openpayAPI.PseService.Create(request);

Ejemplo de respuesta

{
    "orderId":"oid-12524",
    "redirect_url":"https://sandbox-api.openpay.mx/v1/maonhzpqm8xp2ydssovf/customers/ah8tdi7gr9zll6ejijuu/checkouts/ckqtz7smmjffvc4jgfko/pse"
}

Clientes

Los clientes son recursos en Openpay que se manejan dentro de su cuenta de comercio y puede representar usuarios, clientes o socios segun el tipo de negocio.

A los clientes les puedes agregar tarjetas para despues realizar transacciones de Cargo

Objeto Cliente

Propiedad	Descripción
id	*string* Identificador único del cliente.
creation_date	*datetime* Fecha y hora en que se creó el cliente en formato ISO 8601
name	*string* Nombre del cliente.
last_name	*string* Apellidos del cliente.
email	*string* Cuenta de correo electrónico del cliente.
phone_number	*numeric* Número telefónico del Cliente.
status	*string* Estatus de la cuenta del cliente puede ser active o deleted. Si la cuenta se encuentra en estatus deleted no se permite realizar ninguna transacción.
balance	*numeric* Saldo en la cuenta con dos decimales.
creation_date	*datetime* Fecha en que se creó el nuevo cliente.
external_id	*string* Identificador externo único para el cliente asignado por el comercio.
customer_address	*object* Dirección del Cliente. Usada comúnmente como dirección de envío.
clabe	*string* No tiene uso por el momento.

cURL

PHP

JAVA

cURL

Objeto Cliente

Ejemplo de objeto

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address" : null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

PHP

Objeto Cliente

Ejemplo de objeto

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address" : null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

JAVA

Objeto Cliente

Ejemplo de objeto

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address" : null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

Objeto Cliente

Ejemplo de objeto

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address" : null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

Crear un nuevo cliente

Crea un objeto cliente.

Petición

Propiedad	Descripción
external_id	*string* (opcional, longitud = 100) Identificador externo único para el cliente asignado por el comercio.
name	*string* (requerido, longitud = 100) Nombre(s) del cliente.
last_name	*string* (opcional, longitud = 100) Apellidos del cliente.
email	*string* (requerido, longitud = 100) Cuenta de correo electrónico del Cliente.
requires_account	*boolean* (opcional, default = false) Enviar con valor true si requiere que el cliente se cree con cuenta para manejo del saldo. Para usar módulo PSE este campo debe ir en false.
phone_number	*string* (opcional, longitud = 100) Número telefónico del Cliente.
customer_address	*object* (opcional) Dirección del Cliente. Usada comúnmente como dirección de envío.

Respuesta

Un objeto cliente en caso que se hayan enviado todos los datos correctamente, o una respuesta de error si ocurrió algún problema en la creación.

cURL

PHP

JAVA

cURL

Crear un nuevo cliente

Definición

POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
   'external_id' : '',
   "name": "Pedro Diego",
   "last_name": "Alatorre Martínez",
   "email": "pedro.alatorre@comercio.com",
   "phone_number" : "5744484951",
   "customer_address": {
       "department":"Medellín",
       "city":"Antioquía",
       "additional":"Avenida 7f bis # 138-58 Apartamento 942"
   }
}'

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

PHP

Crear un nuevo cliente

Definición

<?
$customer = $openpay->customers->add(customerData);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab', 'CO');

$customerData = array(
     'external_id' => '',
     'name' => 'Pedro Diego',
     'last_name' => 'Alatorre Martínez',
     'email' => 'pedro.alatorre@comercio.com',
     'phone_number' => '16362801',
     'customer_address' => array(
         'department' => 'Medellín',
         'city' => 'Antioquía',
         'additional' => 'Avenida 7f bis # 138-58 Apartamento 942'
      )
   );

$customer = $openpay->customers->add($customerData);
?>

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

JAVA

Crear un nuevo cliente

Definición

openpayAPI.customers().create(Customer customer);

Ejemplo de petición

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

Crear un nuevo cliente

Definición

openpayAPI.CustomerService.Create(Customer customer);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer request = new Customer();
request.ExternalId = "idExterno0101";
request.Name = "Pedro Diego";
request.LastName = "Alatorre Martínez";
request.Email = "pedro.alatorre@comercio.com";
request.PhoneNumber = "16362801";
request.RequiresAccount = false;
CustomerAddress customerAddress = new CustomerAddress();
customerAddress.Department = "Medellín";
customerAddress.City = "Bogota";
customerAddress.Additional = "Avenida 7f bis # 138-58 Apartamento 942";
request.CustomerAddress = customerAddress;

request = api.CustomerService.Create(request);

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

Actualizar un cliente

Actualiza uno o más datos del cliente.

Petición

Propiedad	Descripción
name	*string* (requerido, longitud = 100) Nombre(s) del cliente.
last_name	*string* (opcional, longitud = 100) Apellidos del cliente.
email	*string* (requerido, longitud = 100) Cuenta de correo electrónico del Cliente.
phone_number	*string* (opcional, longitud = 100) Número telefónico del Cliente.
customer_address	*object* Dirección del Cliente. Usada comúnmente como dirección de envío.

Respuesta

Regresa un objeto cliente con la información actualizada, o una respuesta de error si ocurrió algún problema en la actualización.

cURL

PHP

JAVA

cURL

Actualizar un cliente

Definición

PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/anbnldwgni1way3yp2dw \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X PUT -d '{
   "name": "customer name",
   "email": "customer_email@me.com",
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
   "phone_number":"16362801"
 }'

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

PHP

Actualizar un cliente

Definición

<?
$customer = $openpay->customers->get(customerId);
$customer->save();
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$customer->name = 'Juan';
$customer->last_name = 'Godinez';
$customer->save();
?>

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

JAVA

Actualizar un cliente

Definición

openpayAPI.customers().update(Customer customer);

Ejemplo de petición

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

Actualizar un cliente

Definición

openpayAPI.CustomerService.Update(Customer customer);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer request = new Customer();
request.Name = "Julian Gerardo";
request.LastName = "López Martínez";
request.Email = "julian.martinez@gmail.com";
request.PhoneNumber = "16362801";
CustomerAddress customerAddress = new CustomerAddress();
customerAddress.Department = "Medellín";
customerAddress.City = "Antioquia";
customerAddress.Additional = "Avenida 11e bis #152-43 Apartamento 508";
request.CustomerAddress = customerAddress;

request = api.CustomerService.Update(request);

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

Obtener un cliente existente

Obtiene la información actual de un cliente existente. Solo es necesario especificar el identificador que fue regresado al momento de crear el cliente.

Petición

Propiedad	Descripción
id	string (requerido, longitud = 45) Identificador único del cliente que se desea obtener.

Respuesta

Si el identificador existe regresa un objeto cliente con la información del cliente.

cURL

PHP

JAVA

cURL

Obtener un cliente existente

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/anbnldwgni1way3yp2dw \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json"

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

PHP

Obtener un cliente existente

Definición

<?
$customer = $openpay->customers->get(customerId);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
?>

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

JAVA

Obtener un cliente existente

Definición

openpayAPI.customers().get(String customerId);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer customer = api.customers().get("a9pvykxz4g5rg0fplze0");

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

Obtener un cliente existente

Definición

openpayAPI.CustomerService.Update(string customer_id);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer customer = api.CustomerService.Update("a9pvykxz4g5rg0fplze0");

Ejemplo de respuesta

{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}

Eliminar un cliente

Elimina un cliente permanentemente. Openpay mantiene los registros de las operaciones. El cliente no se podrá borrar si su saldo es mayor a 0 (para cliente con manejo de saldo)

Petición

Propiedad	Descripción
id	string (requerido, longitud = 45) Identificador único del cliente a borrar.

Respuesta

Si el cliente se borra correctamente la respuesta es vacía, si no se puede borrar se regresa un objeto error indicando el motivo.

cURL

PHP

JAVA

cURL

Eliminar un cliente

Definición

DELETE https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/anbnldwgni1way3yp2dw \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X DELETE

PHP

Eliminar un cliente

Definición

<?
$customer = $openpay->customers->get(customerId);
$customer->delete();
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$customer->delete();
?>

JAVA

Eliminar un cliente

Definición

openpayAPI.customers().delete(String customerId);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.customers().delete("a9pvykxz4g5rg0fplze0");

Eliminar un cliente

Definición

openpayAPI.CustomerService.Delete(string customer_id);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.CustomerService.Delete("a9pvykxz4g5rg0fplze0");

Listado de clientes

Regresa una lista de los cliente registrados, si desea delimitar el resultado se pueden utilizar los filtros.

Petición

Puede realizar una búsqueda utilizando los siguiente parámetros como filtros.

Propiedad	Descripción
external_id	string Identificador único del cliente asignado por el comercio que se desea obtener.
creation	*date* Igual a la fecha de creación del cliente. Formato yyyy-mm-dd
creation[gte]	*date* Mayor a la fecha de creación del cliente .Formato yyyy-mm-dd
creation[lte]	*date* Menor a la fecha de creación del cliente .Formato yyyy-mm-dd
offset	*numeric* Número de registros a omitir al inicio, por defecto 0.
limit	*numeric* Número de registros que se requieren, por defecto 10.

Respuesta

Regresa un arreglo de objetos cliente.

cURL

PHP

JAVA

cURL

Listado de clientes

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers

Ejemplo de petición

curl -g "https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers?creation[gte]=2013-11-01&limit=2" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json"

Ejemplo de respuesta

[{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}]

PHP

Listado de clientes

Definición

<?
$customerList = $openpay->customers->getList(findDataRequest);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$findDataRequest = array(
    'creation[gte]' => '2018-01-01',
    'creation[lte]' => '2018-12-31',
    'offset' => 0,
    'limit' => 5);

$customerList = $openpay->customers->getList($findDataRequest);
?>

Ejemplo de respuesta

[{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}]

JAVA

Listado de clientes

Definición

openpayAPI.customers().list(SearchParams request);

Ejemplo de petición

final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2018, 5, 1, 0, 0, 0);
dateLte.set(2018, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<Customer> customers = api.customers().list(request);

Ejemplo de respuesta

[{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}]

Listado de clientes

Definición

openpayAPI.CustomerService.List(SearchParams request = null);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2018, 5, 1);
request.CreationLte = new DateTime(2018, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Customer> customers = api.CustomerService.List(request);

Ejemplo de respuesta

[{
    "id": "awfx3738muksxzgrynwb",
    "name": "Pedro Diego",
    "last_name": "Alatorre Martínez",
    "email": "pedro.alatorre@comercio.com",
    "phone_number": "5744484951",
    "status": "active",
    "balance": 0.00,
    "creation_date": "2018-10-31T11:39:21-06:00",
    "external_id": null,
    "address": null,
    "customer_address": {
        "department": "Medellín",
        "city": "Antioquía",
        "additional": "Avenida 7f bis # 138-58 Apartamento 942"
    },
    "clabe": null
}]

Tarjetas

Dentro de la plataforma Openpay podrás agregar tarjetas a la cuenta del cliente, eliminarlas, recuperar alguna en específico y listarlas.

Se pueden almacenar múltiples tarjetas de débito y/o crédito a nivel cliente o a nivel comercio para realizar cargos posteriormente sin la necesidad de introducir nuevamente la información.

Objeto Tarjeta

Propiedad	Descripción
id	*string* Identificador único de la tarjeta.
creation_date	*datetime* Fecha y hora en que se creó la tarjeta en formato ISO 8601
holder_name	*string* Nombre del tarjeta habiente.
card_number	*numeric* Número de tarjeta, puede ser de 16 o 19 dígitos.
cvv2	*numeric* Código de seguridad como aparece en la parte de atrás de la tarjeta. Generalmente 3 dígitos.
expiration_month	*numeric* Mes de expiración tal como aparece en la tarjeta.
expiration_year	*numeric* Año de expiración tal como aparece en la tarjeta.
address	*object* Por el momento no se usa.
allows_charges	*boolean* Permite conocer si se pueden realizar cargos a la tarjeta.
brand	*string* Marca de la tarjeta: visa, mastercard, carnet o american express.
type	*string* Tipo de la tarjeta: debit, credit, cash, etc.
bank_name	*string* Nombre del banco emisor.
bank_code	*string* Código del banco emisor.
customer_id	*string* Identificador del cliente al que pertenece la tarjeta. Si la tarjeta es a nivel comercio este valor será null.

cURL

PHP

JAVA

cURL

Objeto Tarjeta

Ejemplo de objeto

{
   "type":"debit",
   "brand":"mastercard",
   "address":null,
   "id":"kgipbqixvjg3gbzowl7l",
   "card_number":"1111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "allows_charges":true,
   "creation_date":"2018-12-12T17:50:00-06:00",
   "bank_name":"BANCO DE COLOMBIA",
   "bank_code":"000",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

PHP

Objeto Tarjeta

Ejemplo de objeto

{
   "type":"debit",
   "brand":"mastercard",
   "address":null,
   "id":"kgipbqixvjg3gbzowl7l",
   "card_number":"1111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "allows_charges":true,
   "creation_date":"2018-12-12T17:50:00-06:00",
   "bank_name":"BANCO DE COLOMBIA",
   "bank_code":"000",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

JAVA

Objeto Tarjeta

Ejemplo de objeto

{
   "type":"debit",
   "brand":"mastercard",
   "address":null,
   "id":"kgipbqixvjg3gbzowl7l",
   "card_number":"1111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "allows_charges":true,
   "creation_date":"2018-12-12T17:50:00-06:00",
   "bank_name":"BANCO DE COLOMBIA",
   "bank_code":"000",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

Objeto Tarjeta

Ejemplo de objeto

{
   "type":"debit",
   "brand":"mastercard",
   "address":null,
   "id":"kgipbqixvjg3gbzowl7l",
   "card_number":"1111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "allows_charges":true,
   "creation_date":"2018-12-12T17:50:00-06:00",
   "bank_name":"BANCO DE COLOMBIA",
   "bank_code":"000",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

Crear una tarjeta

Cuando se crea una tarjeta debe especificarse cliente, si no se especifica el cliente la tarjeta quedará registrada para la cuenta del comercio. Una vez guardada la tarjeta no se puede obtener el número y código de seguridad.

Nota: Todas las tarjetas al momento de guardarse en Openpay son validadas haciendo un autorización por $10.00 los cuales son devueltos en el momento.

Al momento de guardar la tarjeta se generará un id que podrá ser usado para hacer cargos a la tarjeta, envíos a una tarjeta o simplemente obtener la información no sensible de la tarjeta.

Cuando se crea una tarjeta puede usarse o no la implementación del sistema antifraude. La propiedad device_session_id deberá ser generada desde el API JavaScript, véase Fraud detection using device data.

Petición

Propiedad	Descripción
holder_name	*string* (requerido, longitud = 80) Nombre del tarjeta habiente.
card_number	*numeric* (requerido) Numero de tarjeta puede ser de 16 o 19 dígitos.
cvv2	*numeric* (requerido) Código de seguridad como aparece en la parte de atrás de la tarjeta. Generalmente 3 dígitos.
expiration_month	*numeric* (requerido) Mes de expiración tal como aparece en la tarjeta.
expiration_year	*numeric* (requerido) Año de expiración tal como aparece en la tarjeta.
device_session_id	*string* (opcional, longitud = 255) Identificador del dispositivo generado con la herramienta antifraudes.

Respuesta

Regresa un objeto tarjeta cuando se creó correctamente o una respuesta de error si ocurrió algún problema en la creación.

cURL

PHP

JAVA

cURL

Crear una tarjeta

Definición

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/cards

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
  "holder_name":"DinnersClub",
  "card_number":"36728481533333",
  "cvv2":"651",
  "expiration_month":"07",
  "expiration_year":"21",
  "device_session_id" : "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f"
}'

Ejemplo de respuesta

{
     "id": "kulqltitbq0wnk3l2q3c",
     "type": "debit",
     "brand": "visa",
     "address": null,
     "card_number":"411111XXXXXX1111",
     "holder_name":"Juan Perez Ramirez",
     "expiration_year":"20",
     "expiration_month":"12",
     "allows_charges":true,
     "creation_date":"2018-05-21T17:31:01-05:00",
     "bank_name":"BBVA",
     "bank_code":"000"
}

PHP

Crear una tarjeta

Definición

<?
//Cliente
$customer = $openpay->customers->get(customerId);
$card = $customer->cards->add(cardDataRequest);

//Comercio
$card = $openpay->cards->add(cardDataRequest);
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$cardDataRequest = array(
    'holder_name' => 'Teofilo Velazco',
    'card_number' => '4916394462033681',
    'cvv2' => '123',
    'expiration_month' => '12',
    'expiration_year' => '15',
    'device_session_id' => 'kR1MiQhz2otdIuUlQkbEyitIqVMiI16f'
);

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->add($cardDataRequest);
?>

Ejemplo de respuesta

{
     "id": "kulqltitbq0wnk3l2q3c",
     "type": "debit",
     "brand": "visa",
     "address": null,
     "card_number":"411111XXXXXX1111",
     "holder_name":"Juan Perez Ramirez",
     "expiration_year":"20",
     "expiration_month":"12",
     "allows_charges":true,
     "creation_date":"2018-05-21T17:31:01-05:00",
     "bank_name":"BBVA",
     "bank_code":"000"
}

JAVA

Crear una tarjeta

Definición

//Cliente
openpayAPI.cards().create(String customerId, Card request);

//Comercio
openpayAPI.cards().create(Card request);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card request = new Card();
request.holderName("Juan Perez Ramirez");
request.cardNumber("4111111111111111");
request.cvv2("110");
request.expirationMonth(12);
request.expirationYear(20);
request.deviceSessionId("kR1MiQhz2otdIuUlQkbEyitIqVMiI16f");


request = api.cards().create("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

{
     "id": "kulqltitbq0wnk3l2q3c",
     "type": "debit",
     "brand": "visa",
     "address": null,
     "card_number":"411111XXXXXX1111",
     "holder_name":"Juan Perez Ramirez",
     "expiration_year":"20",
     "expiration_month":"12",
     "allows_charges":true,
     "creation_date":"2018-05-21T17:31:01-05:00",
     "bank_name":"BBVA",
     "bank_code":"000"
}

Crear una tarjeta

Definición

//Cliente
openpayAPI.CardService.Create(string customer_id, Card card);

//Comercio
openpayAPI.CardService.Create(Card card);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card request = new Card();
request.HolderName = "Juan Perez Ramirez";
request.CardNumber = "4111111111111111";
request.Cvv2 = "110";
request.ExpirationMonth = "12";
request.ExpirationYear = "20";
request.DeviceSessionId = "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f";


request = api.CardService.Create("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

{
     "id": "kulqltitbq0wnk3l2q3c",
     "type": "debit",
     "brand": "visa",
     "address": null,
     "card_number":"411111XXXXXX1111",
     "holder_name":"Juan Perez Ramirez",
     "expiration_year":"20",
     "expiration_month":"12",
     "allows_charges":true,
     "creation_date":"2018-05-21T17:31:01-05:00",
     "bank_name":"BBVA",
     "bank_code":"000"
}

Crear una tarjeta con token

Crea una tarjeta a partir de un token obtenido desde el navegador o dispositivo del cliente. Esta forma evita que la información sensible de la tarjeta pase por tus servidores.

Petición

Propiedad	Descripción
token_id	*string* (requerido, longitud = 45) Identificador del token generado en el navegador o dispositivo del cliente.
device_session_id	*string* (requerido, longitud = 255) Identificador del dispositivo generado con la herramienta antifraudes

Respuesta

Regresa un objeto tarjeta

cURL

PHP

JAVA

cURL

Crear una tarjeta con token

Definición

Comercio
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/cards

Cliente
POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
      "token_id":"tokgslwpdcrkhlgxqi9a",
      "device_session_id":"8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o"
   }'

Ejemplo de respuesta

{
    "id": "kh6u8t1agrjhh4sz3vlt",
    "type": "debit",
    "brand": "visa",
    "address": null,
    "card_number": "457562XXXXXX0326",
    "holder_name": "Jorge Lopez",
    "expiration_year": "19",
    "expiration_month": "12",
    "allows_charges": true,
    "creation_date": "2019-08-12T13:14:34-05:00",
    "bank_name": "BBVA COLOMBIA",
    "bank_code": "000",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

PHP

Crear una tarjeta con token

Definición

<?
//Cliente
$customer = $openpay->customers->get(customerId);
$card = $customer->cards->add(cardDataRequest);

//Comercio
$card = $openpay->cards->add(cardDataRequest);
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$cardDataRequest = array(
    'token_id' => 'tokgslwpdcrkhlgxqi9a',
    'device_session_id' => '8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o'
    );

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->add($cardDataRequest);
?>

Ejemplo de respuesta

{
    "id": "kh6u8t1agrjhh4sz3vlt",
    "type": "debit",
    "brand": "visa",
    "address": null,
    "card_number": "457562XXXXXX0326",
    "holder_name": "Jorge Lopez",
    "expiration_year": "19",
    "expiration_month": "12",
    "allows_charges": true,
    "creation_date": "2019-08-12T13:14:34-05:00",
    "bank_name": "BBVA COLOMBIA",
    "bank_code": "000",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

JAVA

Crear una tarjeta con token

Definición

//Cliente
openpayAPI.cards().create(String customerId, Card card);

//Comercio
openpayAPI.cards().create(Card card);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card request = new Card();
request.tokenId("tokgslwpdcrkhlgxqi9a");
request.deviceSessionId("8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o");

request = api.cards().create("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

{
    "id": "kh6u8t1agrjhh4sz3vlt",
    "type": "debit",
    "brand": "visa",
    "address": null,
    "card_number": "457562XXXXXX0326",
    "holder_name": "Jorge Lopez",
    "expiration_year": "19",
    "expiration_month": "12",
    "allows_charges": true,
    "creation_date": "2019-08-12T13:14:34-05:00",
    "bank_name": "BBVA COLOMBIA",
    "bank_code": "000",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

Crear una tarjeta con token

Definición

//Cliente
openpayAPI.CardService.Create(string customer_id, Card request);

//Comercio
openpayAPI.CardService.Create(Card request);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card request = new Card();
request.TokenId = "tokgslwpdcrkhlgxqi9a";
request.DeviceSessionId = "8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o";

request = api.CardService.Create("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

{
    "id": "kh6u8t1agrjhh4sz3vlt",
    "type": "debit",
    "brand": "visa",
    "address": null,
    "card_number": "457562XXXXXX0326",
    "holder_name": "Jorge Lopez",
    "expiration_year": "19",
    "expiration_month": "12",
    "allows_charges": true,
    "creation_date": "2019-08-12T13:14:34-05:00",
    "bank_name": "BBVA COLOMBIA",
    "bank_code": "000",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

Obtener una tarjeta

Obtiene los detalles de una tarjeta solicitándola con su id.

Nota: Nunca se regresarán datos sensibles como son el código de seguridad y del número de tarjeta sólo se mostraran los primeros 6 y los últimos 4 dígitos.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador único de la tarjeta

Respuesta

Regresa un objeto tarjeta

cURL

PHP

JAVA

cURL

Obtener una tarjeta

Definición

Comercio
GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/cards/{CARD_ID}

Cliente
GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/ktrpvymgatocelsciak7 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json"

Ejemplo de respuesta

{
     "id": "kulqltitbq0wnk3l2q3c",
     "type": "debit",
     "brand": "visa",
     "address": null,
     "card_number":"411111XXXXXX1111",
     "holder_name":"Juan Perez Ramirez",
     "expiration_year":"20",
     "expiration_month":"12",
     "allows_charges":true,
     "creation_date":"2018-05-21T17:31:01-05:00",
     "bank_name":"BBVA",
     "bank_code":"000"
}

PHP

Obtener una tarjeta

Definición

<?
//Cliente
$customer = $openpay->customers->get(customerId);
$card = $customer->cards->get(cardId);

//Comercio
$card = $openpay->cards->get(cardId);
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->get('k9pn8qtsvr7k7gxoq1r5');
?>

Ejemplo de respuesta

{
     "id": "kulqltitbq0wnk3l2q3c",
     "type": "debit",
     "brand": "visa",
     "address": null,
     "card_number":"411111XXXXXX1111",
     "holder_name":"Juan Perez Ramirez",
     "expiration_year":"20",
     "expiration_month":"12",
     "allows_charges":true,
     "creation_date":"2018-05-21T17:31:01-05:00",
     "bank_name":"BBVA",
     "bank_code":"000"
}

JAVA

Obtener una tarjeta

Definición

//Cliente
openpayAPI.cards().get(String customerId, String cardId);

//Comercio
openpayAPI.cards().get(String cardId);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card card = api.cards().get("a9pvykxz4g5rg0fplze0", "ktrpvymgatocelsciak7");

Ejemplo de respuesta

{
     "id": "kulqltitbq0wnk3l2q3c",
     "type": "debit",
     "brand": "visa",
     "address": null,
     "card_number":"411111XXXXXX1111",
     "holder_name":"Juan Perez Ramirez",
     "expiration_year":"20",
     "expiration_month":"12",
     "allows_charges":true,
     "creation_date":"2018-05-21T17:31:01-05:00",
     "bank_name":"BBVA",
     "bank_code":"000"
}

Obtener una tarjeta

Definición

//Cliente
openpayAPI.CardService.Get(string customer_id, string card_id);

//Comercio
openpayAPI.CardService.Get(string card_id);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card card = api.CardService.Get("a9pvykxz4g5rg0fplze0", "ktrpvymgatocelsciak7");

Ejemplo de respuesta

{
     "id": "kulqltitbq0wnk3l2q3c",
     "type": "debit",
     "brand": "visa",
     "address": null,
     "card_number":"411111XXXXXX1111",
     "holder_name":"Juan Perez Ramirez",
     "expiration_year":"20",
     "expiration_month":"12",
     "allows_charges":true,
     "creation_date":"2018-05-21T17:31:01-05:00",
     "bank_name":"BBVA",
     "bank_code":"000"
}

Eliminar una tarjeta

Elimina una tarjeta del cliente o comercio. Una vez eliminada no se permitirá hacer movimientos, sin embargo, se mantendrán todos los registros de operaciones que haya realizado y se podrán consultar en el dashboard.

Para eliminarla sólo es necesario proporcionar el identificador de la tarjeta.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador único de la tarjeta

Respuesta

Si la tarjeta se borra correctamente la respuesta es vacía, si no se puede borrar se regresa un objeto error indicando el motivo.

cURL

PHP

JAVA

cURL

Eliminar una tarjeta

Definición

Comercio
DELETE https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/cards/{CARD_ID}

Cliente
DELETE https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/ktrpvymgatocelsciak7 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE

PHP

Eliminar una tarjeta

Definición

<?
//Cliente
$customer = $openpay->customers->get(customerId);
$card = $customer->cards->get(cardId);
$card->delete();

//Comercio
$card = $openpay->cards->get(cardId);
$card->delete();
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->get('k9pn8qtsvr7k7gxoq1r5');
$card->delete();
?>

JAVA

Eliminar una tarjeta

Definición

//Cliente
openpayAPI.cards().delete(String customerId, String cardId);

//Comercio
openpayAPI.cards().delete(String cardId);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.cards().delete("a9pvykxz4g5rg0fplze0", "ktrpvymgatocelsciak7");

Eliminar una tarjeta

Definición

//Cliente
openpayAPI.CardService.Delete(string customer_id, string card_id);

//Comercio
openpayAPI.CardService.Delete(string card_id);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.CardService.Delete("a9pvykxz4g5rg0fplze0", "ktrpvymgatocelsciak7");

Listado de tarjetas

Regresa una lista de las tarjetas registrados por comercio o cliente, si desea delimitar el resultado se pueden utilizar los filtros.

Petición

Puede realizar una búsqueda utilizando los siguiente parámetros como filtros.

Propiedad	Descripción
creation	*date* Igual a la fecha de creación. Formato yyyy-mm-dd
creation[gte]	*date* Mayor a la fecha de creación. Formato yyyy-mm-dd
creation[lte]	*date* Menor a la fecha de creación. Formato yyyy-mm-dd
offset	*numeric* Número de registros a omitir al inicio, por defecto 0.
limit	*numeric* Número de registros que se requieren, por defecto 10.

Respuesta

Listado de objetos tarjeta registrados de acuerdo a los parámetros proporcionados, ordenadas por fecha de creación en orden descendente.

cURL

PHP

JAVA

cURL

Listado de tarjetas

Definición

Comercio
GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers

Cliente
GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards

Ejemplo de petición con cliente

curl -g "https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards?limit=2" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Ejemplo de respuesta

[
    {
    "id": "kulqltitbq0wnk3l2q3c",
    "type": "debit",
    "brand": "visa",
    "address": null,
    "card_number":"411111XXXXXX1111",
    "holder_name":"Juan Perez Ramirez",
    "expiration_year":"20",
    "expiration_month":"12",
    "allows_charges":true,
    "creation_date":"2018-05-21T17:31:01-05:00",
    "bank_name":"BBVA",
    "bank_code":"000"
    },
    {
    "id":"kgjy0jiami01kkpdoywr",
    "type":"debit",
    "brand":"mastercard",
    "address": null,
    "card_number":"1111",
    "holder_name":"Pedro Paramo",
    "expiration_year":"15",
    "expiration_month":"12",
    "allows_charges":true,
    "creation_date":"2013-11-19T13:26:12-06:00",
    "bank_name":"BBVA BANCOMER",
    "bank_code":"012"
    }
]

PHP

Listado de tarjetas

Definición

<?
//Clientes
$customer = $openpay->customers->get(customerId);
$cardList = $customer->cards->getList(findDataRequest);

//Comercio
$cardList = $openpay->cards->getList(findDataRequest);
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$findDataRequest = array(
    'creation[gte]' => '2013-01-01',
    'creation[lte]' => '2013-12-31',
    'offset' => 0,
    'limit' => 5);

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$cardList = $customer->cards->getList($findDataRequest);
?>

Ejemplo de respuesta

[
    {
    "id": "kulqltitbq0wnk3l2q3c",
    "type": "debit",
    "brand": "visa",
    "address": null,
    "card_number":"411111XXXXXX1111",
    "holder_name":"Juan Perez Ramirez",
    "expiration_year":"20",
    "expiration_month":"12",
    "allows_charges":true,
    "creation_date":"2018-05-21T17:31:01-05:00",
    "bank_name":"BBVA",
    "bank_code":"000"
    },
    {
    "id":"kgjy0jiami01kkpdoywr",
    "type":"debit",
    "brand":"mastercard",
    "address": null,
    "card_number":"1111",
    "holder_name":"Pedro Paramo",
    "expiration_year":"15",
    "expiration_month":"12",
    "allows_charges":true,
    "creation_date":"2013-11-19T13:26:12-06:00",
    "bank_name":"BBVA BANCOMER",
    "bank_code":"012"
    }
]

JAVA

Listado de tarjetas

Definición

//Cliente
openpayAPI.cards().list(String customerId, SearchParams request);

//Comercio
openpayAPI.cards().list(SearchParams request);

Ejemplo de petición con cliente

final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);
List<Card> cards = api.cards().list("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

[
    {
    "id": "kulqltitbq0wnk3l2q3c",
    "type": "debit",
    "brand": "visa",
    "address": null,
    "card_number":"411111XXXXXX1111",
    "holder_name":"Juan Perez Ramirez",
    "expiration_year":"20",
    "expiration_month":"12",
    "allows_charges":true,
    "creation_date":"2018-05-21T17:31:01-05:00",
    "bank_name":"BBVA",
    "bank_code":"000"
    },
    {
    "id":"kgjy0jiami01kkpdoywr",
    "type":"debit",
    "brand":"mastercard",
    "address": null,
    "card_number":"1111",
    "holder_name":"Pedro Paramo",
    "expiration_year":"15",
    "expiration_month":"12",
    "allows_charges":true,
    "creation_date":"2013-11-19T13:26:12-06:00",
    "bank_name":"BBVA BANCOMER",
    "bank_code":"012"
    }
]

Listado de tarjetas

Definición

//Cliente
openpayAPI.CardService.List(string customer_id, SearchParams request = null);

//Comercio
openpayAPI.CardService.List(SearchParams request = null);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Card> cards = api.CardService.List("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

[
    {
    "id": "kulqltitbq0wnk3l2q3c",
    "type": "debit",
    "brand": "visa",
    "address": null,
    "card_number":"411111XXXXXX1111",
    "holder_name":"Juan Perez Ramirez",
    "expiration_year":"20",
    "expiration_month":"12",
    "allows_charges":true,
    "creation_date":"2018-05-21T17:31:01-05:00",
    "bank_name":"BBVA",
    "bank_code":"000"
    },
    {
    "id":"kgjy0jiami01kkpdoywr",
    "type":"debit",
    "brand":"mastercard",
    "address": null,
    "card_number":"1111",
    "holder_name":"Pedro Paramo",
    "expiration_year":"15",
    "expiration_month":"12",
    "allows_charges":true,
    "creation_date":"2013-11-19T13:26:12-06:00",
    "bank_name":"BBVA BANCOMER",
    "bank_code":"012"
    }
]

Actualizar tarjeta

Actualiza los datos de una tarjeta desde el navegador o dispositivo del cliente. También permite enviar un cvv2 que se usará en el próximo cargo que se realice a esta tarjeta. De esta forma evita que la información sensible de la tarjeta pase por tus servidores.

Petición

Propiedad	Descripción
holder_name	*string* (opcional) Nombre del tarjeta habiente.
cvv2	*string* (opcional) Código de seguridad como aparece en la parte de atrás de la tarjeta. Generalmente 3 dígitos.
expiration_month	*numeric* (opcional) Mes de expiración tal como aparece en la tarjeta.
expiration_year	*numeric* (opcional) Año de expiración tal como aparece en la tarjeta.
merchant_id	*string* (condicional) ID del comercio. Usado solamente cuando se usa un grupo de comercio.

Respuesta

Actualmente regresa un JSON sin datos. Considerar que se podría extender la respuesta en el futuro.

cURL

PHP

JAVA

cURL

Actualizar tarjeta

Definición

Comercio
PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/cards/{CARD_ID}

Cliente
PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/kysc8pycq8hnlzivk1x4 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X PUT -d '{
      "cvv2":"000"
   }'

Ejemplo de respuesta

{
}

PHP

Actualizar tarjeta

Definición

Comercio
PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/cards/{CARD_ID}

Cliente
PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Ejemplo de petición con cliente

Ejemplo de respuesta

{
}

JAVA

Actualizar tarjeta

Definición

Comercio
PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/cards/{CARD_ID}

Cliente
PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Ejemplo de petición con cliente

Ejemplo de respuesta

{
}

Actualizar tarjeta

Definición

Comercio
PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/cards/{CARD_ID}

Cliente
PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Ejemplo de petición con cliente

Ejemplo de respuesta

{
}

Planes

Los planes son recursos en Openpay que permiten crear plantillas para las suscripciones. Con ellos podrás definir la cantidad y frecuencia con la que se realizarán los cargos recurrentes.

Objeto Plan

Propiedad	Descripción
id	*string* Identificador único del Plan.
creation_date	*datetime* Fecha y hora en que se creó el Plan en formato ISO 8601
name	*string* Nombre del Plan.
amount	*numeric* Monto que se aplicara cada vez que se cobre la suscripción. Debe ser una cantidad mayor a cero.
currency	*string* Moneda usada en la operación, por default es COP
repeat_every	*numeric* Número de unidades tiempo entre los que se cobrara la suscripción. Por ejemplo, repeat_unit=month y repeat_every=2 indica que se cobrara cada 2 meses.
repeat_unit	*string* Especifica la frecuencia de cobro. Puede ser semanal(week), mensual(month) o anual(year).
retry_times	*numeric* Numero de reintentos de cobro de la suscripción. Cuando se agotan los intentos se pone en el estatus determinado por el campo status_after_retry.
status	*string* Estatus del Plan puede ser active o deleted. Si el plan se encuentra en estado deleted no se permite registrar nuevas suscripciones, pero las que ya están registradas, se siguen cobrando.
status_after_retry	*string* Este campo especifica el status en el que se pondrá la suscripción una vez que se agotaron los intentos. Puede ser: unpaid o cancelled
trial_days	*numeric* Numero de días de prueba por defecto que tendrá la suscripción.

cURL

PHP

JAVA

cURL

Objeto Plan

Ejemplo de objeto

{
    "name": "Curso de ingles",
    "status": "active",
    "amount": 150,
    "currency": "COP",
    "id": "patpflacwilazguj6bem",
    "creation_date": "2013-12-13T09:43:52-06:00",
    "repeat_every": 1,
    "repeat_unit": "month",
    "retry_times": 2,
    "status_after_retry": "cancelled",
    "trial_days": 30
}

PHP

Objeto Plan

Ejemplo de objeto

{
    "name": "Curso de ingles",
    "status": "active",
    "amount": 150,
    "currency": "COP",
    "id": "patpflacwilazguj6bem",
    "creation_date": "2013-12-13T09:43:52-06:00",
    "repeat_every": 1,
    "repeat_unit": "month",
    "retry_times": 2,
    "status_after_retry": "cancelled",
    "trial_days": 30
}

JAVA

Objeto Plan

Ejemplo de objeto

{
    "name": "Curso de ingles",
    "status": "active",
    "amount": 150,
    "currency": "COP",
    "id": "patpflacwilazguj6bem",
    "creation_date": "2013-12-13T09:43:52-06:00",
    "repeat_every": 1,
    "repeat_unit": "month",
    "retry_times": 2,
    "status_after_retry": "cancelled",
    "trial_days": 30
}

Objeto Plan

Ejemplo de objeto

{
    "name": "Curso de ingles",
    "status": "active",
    "amount": 150,
    "currency": "COP",
    "id": "patpflacwilazguj6bem",
    "creation_date": "2013-12-13T09:43:52-06:00",
    "repeat_every": 1,
    "repeat_unit": "month",
    "retry_times": 2,
    "status_after_retry": "cancelled",
    "trial_days": 30
}

Crear un nuevo plan

Crea un nuevo plan al se podrán suscribir uno o varios clientes.

Petición

Propiedad	Descripción
name	*string* (requerido, longitud = 255) Nombre del Plan.
amount	*numeric* (requerido) Monto que se aplicara cada vez que se cobre la suscripción. Debe ser una cantidad mayor a cero.
repeat_every	*numeric* (requerido) Número de unidades tiempo entre los que se cobrara la suscripción. Por ejemplo, repeat_unit=month y repeat_every=2 indica que se cobrara cada 2 meses.
repeat_unit	*numeric* (requerido) Especifica la frecuencia de cobro. Puede ser semanal(week), mensual(month) o anual(year).
retry_times	*numeric* (opcional) Numero de reintentos de cobro de la suscripción. Cuando se agotan los intentos se pone en el estado determinado por el campo status_after_retry.
status_after_retry	*string* (requerido, valores = “UNPAID/CANCELLED”) Este campo especifica el status en el que se pondrá la suscripción una vez que se agotaron los intentos. Puede ser: unpaid o cancelled
trial_days	*numeric* (requerido) Numero de días de prueba por defecto que tendrán las suscripciones que se creen a partir del plan creado.

Respuesta

Regresa un objeto plan creado o un error en caso de ocurrir algún problema.

cURL

PHP

JAVA

cURL

Crear un nuevo plan

Definición

POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/plans

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/plans \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
  "amount": 150,
  "status_after_retry": "cancelled",
  "retry_times": 2,
  "name": "Curso de ingles",
  "repeat_unit": "month",
  "trial_days": "30",
  "repeat_every": "1"
}'

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de ingles",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":30
}

PHP

Crear un nuevo plan

Definición

<?
$plan = $openpay->plans->add(planDataRequest);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$planDataRequest = array(
    'amount' => 150,
    'status_after_retry' => 'cancelled',
    'retry_times' => 2,
    'name' => 'Plan Curso Verano',
    'repeat_unit' => 'month',
    'trial_days' => '30',
    'repeat_every' => '1',
    'currency' => 'COP');

$plan = $openpay->plans->add($planDataRequest);
?>

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de ingles",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":30
}

JAVA

Crear un nuevo plan

Definición

openpayAPI.plans().create(Plan request);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan request = new Plan();
request.name("Curso de ingles");
request.amount(new BigDecimal("150"));
request.repeatEvery(1, PlanRepeatUnit.WEEK);
request.retryTimes(3);
request.statusAfterRetry(PlanStatusAfterRetry.UNPAID);
request.trialDays(30);

request = api.plans().create(request);

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de ingles",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":30
}

Crear un nuevo plan

Definición

openpayAPI.PlanService.Create(Plan plan);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan request = new Plan();
request.Name = "Curso de ingles";
request.Amount = new Decimal(150);
request.RepeatEvery = 1;
request.RepeatUnit = "week";
request.RetryTimes = 2;
request.StatusAfterRetry = "unpaid";
request.TrialDays = 30;

request = api.PlanService.Create(request);

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de ingles",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":30
}

Actualizar un plan existente

Actualiza la información de un plan. Se requiere tener el id del plan y solo se puede actualizar cierta información.

Petición

Propiedad	Descripción
name	*string* (opcional, longitud = 80) Nombre del Plan.
trial_days	*numeric* (opcional) Numero de días de prueba por defecto que tendrán las suscripciones que se creen a partir del plan creado.

Respuesta

Regresa un objeto plan con la información actualizada o una respuesta de error si ocurrió algún problema en la actualización.

cURL

PHP

JAVA

cURL

Actualizar un plan existente

Definición

PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/plans/{PLAN_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/plans/p8e6x3hafqqsbmnoevrt \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X PUT -d '{
      "name": "Curso de aleman",
      "trial_days": "60"
   }'

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

PHP

Actualizar un plan existente

Definición

<?
$plan = $openpay->plans->get(planId);
$plan->save();
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
$plan->name = 'Plan Curso de Verano 2014';
$plan->save();
?>

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

JAVA

Actualizar un plan existente

Definición

openpayAPI.plans().update(Plan request);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan request = new Plan();
request.setId("p8e6x3hafqqsbmnoevrt");
request.name("Curso de ingles");
request.trialDays(30);

request = api.plans().update(request);

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

Actualizar un plan existente

Definición

openpayAPI.PlanService.Update(Plan plan);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan request = new Plan();
request.Id = "p8e6x3hafqqsbmnoevrt";
request.Name = "Curso de ingles";
request.TrialDays = 30;

request = api.PlanService.Update(request);

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

Obtener un plan

Obtiene los detalles de un plan.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador del plan.

Respuesta

Regresa un objeto plan

cURL

PHP

JAVA

cURL

Obtener un plan

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/plans/{PLAN_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/plans/p8e6x3hafqqsbmnoevrt \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

PHP

Obtener un plan

Definición

<?
$plan = $openpay->plans->get(planId);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
?>

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

JAVA

Obtener un plan

Definición

openpayAPI.plans().get(String planId);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan plan = api.plans().get("p8e6x3hafqqsbmnoevrt");

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

Obtener un plan

Definición

openpayAPI.PlanService.Get(string plan_id);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan plan = api.PlanService.Get("p8e6x3hafqqsbmnoevrt");

Ejemplo de respuesta

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150,
   "currency":"COP",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

Eliminar un plan

Al eliminar un plan no se permitirán crear mas suscripciones asociadas a él, sin embargo las suscripciones ya asociadas se mantienen y se continuan cobrando.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador del plan a eliminar

Respuesta

Si el plan se borra correctamente la respuesta es vacía, si no se puede borrar se regresa un objeto error indicando el motivo.

cURL

PHP

JAVA

cURL

Eliminar un plan

Definición

DELETE https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/plans/{PLAN_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/plans/p8e6x3hafqqsbmnoevrt \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE

PHP

Eliminar un plan

Definición

<?
$customer = $openpay->customers->get(customerId);
$plan = $openpay->plans->get(planId);
$plan->delete();
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
$plan->delete();
?>

JAVA

Eliminar un plan

Definición

openpayAPI.plans().delete(String planId);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.plans().delete("p8e6x3hafqqsbmnoevrt");

Eliminar un plan

Definición

openpayAPI.PlanService.Delete(string plan_id);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.PlanService.Delete("p8e6x3hafqqsbmnoevrt");

Listado de planes

Regresa los detalles de todos los planes que están activos.

Petición

Se puede realizar búsquedas utilizando los siguiente parámetros.

Propiedad	Descripción
creation	*date* Igual a la fecha de creación. Formato yyyy-mm-dd
creation[gte]	*date* Mayor a la fecha de creación. Formato yyyy-mm-dd
creation[lte]	*date* Menor a la fecha de creación. Formato yyyy-mm-dd
offset	*numeric* Número de registros a omitir al inicio, por defecto 0.
limit	*numeric* Número de registros que se requieren, por defecto 10.

Respuesta

Listado de objetos plan registrados de acuerdo a los parámetros proporcionados, ordenadas por fecha de creación en orden descendente.

cURL

PHP

JAVA

cURL

Listado de planes

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/plans

Ejemplo de petición

curl -g "https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/plans?limit=10" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Ejemplo de respuesta

[
    {
        "name": "Curso de aleman",
        "status": "active",
        "amount": 150,
        "currency": "COP",
        "id": "patpflacwilazguj6bem",
        "creation_date": "2019-05-13T09:43:52-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 60
    },
    {
        "name": "Curso de ingles",
        "status": "active",
        "amount": 150,
        "currency": "COP",
        "id": "pjl7wfryrrd1tznr0fnl",
        "creation_date": "2019-05-13T11:36:40-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 30
    }
]

PHP

Listado de planes

Definición

<?
$planList = $openpay->plans->getList(findDataRequest);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$findDataRequest = array(
    'creation[gte]' => '2019-01-01',
    'creation[lte]' => '2019-12-31',
    'offset' => 0,
    'limit' => 5);

$planList = $openpay->plans->getList($findDataRequest);
?>

Ejemplo de respuesta

[
    {
        "name": "Curso de aleman",
        "status": "active",
        "amount": 150,
        "currency": "COP",
        "id": "patpflacwilazguj6bem",
        "creation_date": "2019-05-13T09:43:52-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 60
    },
    {
        "name": "Curso de ingles",
        "status": "active",
        "amount": 150,
        "currency": "COP",
        "id": "pjl7wfryrrd1tznr0fnl",
        "creation_date": "2019-05-13T11:36:40-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 30
    }
]

JAVA

Listado de planes

Definición

openpayAPI.plans().list(SearchParams request);

Ejemplo de petición

final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2019, 5, 1, 0, 0, 0);
dateLte.set(2019, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<Plan> plans = api.plans().list(request);

Ejemplo de respuesta

[
    {
        "name": "Curso de aleman",
        "status": "active",
        "amount": 150,
        "currency": "COP",
        "id": "patpflacwilazguj6bem",
        "creation_date": "2019-05-13T09:43:52-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 60
    },
    {
        "name": "Curso de ingles",
        "status": "active",
        "amount": 150,
        "currency": "COP",
        "id": "pjl7wfryrrd1tznr0fnl",
        "creation_date": "2019-05-13T11:36:40-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 30
    }
]

Listado de planes

Definición

openpayAPI.PlanService.List(SearchParams request = null);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2019, 5, 1);
request.CreationLte = new DateTime(2019, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Plan> plans = api.PlanService.List(request);

Ejemplo de respuesta

[
    {
        "name": "Curso de aleman",
        "status": "active",
        "amount": 150,
        "currency": "COP",
        "id": "patpflacwilazguj6bem",
        "creation_date": "2019-05-13T09:43:52-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 60
    },
    {
        "name": "Curso de ingles",
        "status": "active",
        "amount": 150,
        "currency": "COP",
        "id": "pjl7wfryrrd1tznr0fnl",
        "creation_date": "2019-05-13T11:36:40-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 30
    }
]

Suscripciones

Las suscripciones permiten asociar un cliente y una tarjeta para que se pueden realizar cargos recurrentes.

Para poder suscribir algún cliente es necesario primero crear un plan.

Objeto Suscripción

Propiedad	Descripción
id	*string* Identificador único del Plan.
creation_date	*datetime* Fecha y hora en que se creó la suscripción en formato ISO 8601
cancel_at_period_end	*string* Indica si se cancela la suscripción al terminar el periodo.
charge_date	*numeric* Fecha en la que se cobrar la suscripción.
current_period_number	*string* Indica el periodo actual a cobrar.
period_end_date	*numeric* Fecha en la que se termina el periodo actual, un día antes del siguiente cobro.
trial_end_date	*string* Fecha en la que termina el periodo de prueba. Un día después de esta fecha, se realiza el primer cargo.
plan_id	*numeric* Identificador del plan sobre el que se crea la suscripción.
status	*string* Estado de la suscripción puede ser active, “trial”, “past_due”, “unpaid”, o “cancelled”. Si la suscripción tiene periodo de prueba, se pone en status “trial”, si no tiene periodo de prueba, o cuando termino el periodo de prueba y se logro efectuar el primer pago, se pone en “active”, cuando el cobro no logro efectuarse, se coloca en “past_due”, y cuando se agotan los intentos de cobro, se coloca de acuerdo a la configuración del plan, en “unpaid” o en “cancelled”. Cuando se coloca en “unpaid”, y se quiere reactivar la suscripción, es necesario actualizar el medio de pago (tarjeta) de la suscripción. En cualquier otro caso, el status se establece como “cancelled”.
customer_id	*string* Identificador del customer al que pertenece la suscripción.
card	*object* Medio de pago con el cual se cobrará la suscripción. Ver objeto tarjeta

cURL

PHP

JAVA

cURL

Objeto Suscripción

Ejemplo de objeto

{
    "status": "trial",
    "card": {
        "type": "debit",
        "brand": "mastercard",
        "card_number": "1111",
        "holder_name": "Juan Perez Ramirez",
        "expiration_year": "20",
        "expiration_month": "12",
        "allows_charges": true,
        "creation_date": "2018-12-13T12:39:46-06:00",
        "bank_name": "DESCONOCIDO",
        "customer_id": null,
        "bank_code": "000"
    },
    "id": "svxdm1suclzipbi4pavm",
    "cancel_at_period_end": false,
    "charge_date": "2014-01-12",
    "creation_date": "2018-12-13T12:39:46-06:00",
    "current_period_number": 0,
    "period_end_date": "2019-01-11",
    "trial_end_date": "2019-01-11",
    "plan_id": "pjl7wfryrrd1tznr0fnl",
    "customer_id": "a2b79p8xmzeyvmolqfja"
}

PHP

Objeto Suscripción

Ejemplo de objeto

{
    "status": "trial",
    "card": {
        "type": "debit",
        "brand": "mastercard",
        "card_number": "1111",
        "holder_name": "Juan Perez Ramirez",
        "expiration_year": "20",
        "expiration_month": "12",
        "allows_charges": true,
        "creation_date": "2018-12-13T12:39:46-06:00",
        "bank_name": "DESCONOCIDO",
        "customer_id": null,
        "bank_code": "000"
    },
    "id": "svxdm1suclzipbi4pavm",
    "cancel_at_period_end": false,
    "charge_date": "2014-01-12",
    "creation_date": "2018-12-13T12:39:46-06:00",
    "current_period_number": 0,
    "period_end_date": "2019-01-11",
    "trial_end_date": "2019-01-11",
    "plan_id": "pjl7wfryrrd1tznr0fnl",
    "customer_id": "a2b79p8xmzeyvmolqfja"
}

JAVA

Objeto Suscripción

Ejemplo de objeto

{
    "status": "trial",
    "card": {
        "type": "debit",
        "brand": "mastercard",
        "card_number": "1111",
        "holder_name": "Juan Perez Ramirez",
        "expiration_year": "20",
        "expiration_month": "12",
        "allows_charges": true,
        "creation_date": "2018-12-13T12:39:46-06:00",
        "bank_name": "DESCONOCIDO",
        "customer_id": null,
        "bank_code": "000"
    },
    "id": "svxdm1suclzipbi4pavm",
    "cancel_at_period_end": false,
    "charge_date": "2014-01-12",
    "creation_date": "2018-12-13T12:39:46-06:00",
    "current_period_number": 0,
    "period_end_date": "2019-01-11",
    "trial_end_date": "2019-01-11",
    "plan_id": "pjl7wfryrrd1tznr0fnl",
    "customer_id": "a2b79p8xmzeyvmolqfja"
}

Objeto Suscripción

Ejemplo de objeto

{
    "status": "trial",
    "card": {
        "type": "debit",
        "brand": "mastercard",
        "card_number": "1111",
        "holder_name": "Juan Perez Ramirez",
        "expiration_year": "20",
        "expiration_month": "12",
        "allows_charges": true,
        "creation_date": "2018-12-13T12:39:46-06:00",
        "bank_name": "DESCONOCIDO",
        "customer_id": null,
        "bank_code": "000"
    },
    "id": "svxdm1suclzipbi4pavm",
    "cancel_at_period_end": false,
    "charge_date": "2014-01-12",
    "creation_date": "2018-12-13T12:39:46-06:00",
    "current_period_number": 0,
    "period_end_date": "2019-01-11",
    "trial_end_date": "2019-01-11",
    "plan_id": "pjl7wfryrrd1tznr0fnl",
    "customer_id": "a2b79p8xmzeyvmolqfja"
}

Crear una nueva suscripción

Crea una suscripción para un cliente existente. Se puede ocupar una tarjeta previamente creada o se pueden enviar los datos de la tarjeta en donde se realizarán los cargos, estos últimos pueden incluir la propiedad device_session_id para usar la herramienta antifraudes, véase Fraud detection using device data.

Petición

Propiedad	Descripción
plan_id	*string* (requerido, longitud = 45) Identificador del plan sobre el que se crea la suscripción.
trial_end_date	*string* (opcional, longitud = 10) Último día de prueba del cliente. Si no se indica se utilizará el valor de trial_days del plan para calcularlo. Si se indica una fecha anterior al día de hoy, se interpretará como una suscripción sin días de prueba. (Con formato yyy-mm-dd)
source_id	*string* (requerido si no se envía card, longitud = 45) Identificador del token o la tarjeta previamente registrada al cliente con la que se cobrará la suscripción.
card	*object* (requerido si no se envía source_id) Medio de pago con el cual se cobrará la suscripción. Ver objeto tarjeta

Respuesta

Regresa el objeto suscripción creado o una respuesta de error si ocurrió algún problema en la creación.

cURL

PHP

JAVA

cURL

Crear una nueva suscripción

Definición

POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
   "card":{
      "card_number":"4111111111111111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "cvv2":"110",
      "device_session_id":"kR1MiQhz2otdIuUlQkbEyitIqVMiI16f"
   },
   "plan_id":"pbi4kb8hpb64x0uud2eb"
}'

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"002"
   },
   "cancel_at_period_end":false,
   "charge_date":"2019-05-22",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2014-06-20",
   "trial_end_date":"2014-06-20",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

PHP

Crear una nueva suscripción

Definición

<?
$customer = $openpay->customers->get(customerId);
$subscription = $customer->subscriptions->add(subscriptionDataRequest);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$subscriptionDataRequest = array(
    'trial_end_date' => '2019-05-01',
    'plan_id' => 'pbi4kb8hpb64x0uud2eb',
    'card' => array(
         'card_number' => '4111111111111111',
         'holder_name' => 'Juan Perez Ramirez',
         'expiration_year' => '20',
         'expiration_month' => '12',
         'cvv2' => '110',
         'device_session_id' => 'kR1MiQhz2otdIuUlQkbEyitIqVMiI16f'));

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->add($subscriptionDataRequest);
?>

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"002"
   },
   "cancel_at_period_end":false,
   "charge_date":"2019-05-22",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2014-06-20",
   "trial_end_date":"2014-06-20",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

JAVA

Crear una nueva suscripción

Definición

openpayAPI.subscriptions().create(String customerId, Subscription request);

Ejemplo de petición

final Calendar trialEndDate = Calendar.getInstance();
trialEndDate.set(2019, 5, 1, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription request = new Subscription();
request.planId("pbi4kb8hpb64x0uud2eb");
request.trialEndDate(trialEndDate.getTime());
Card card = new Card();
card.cardNumber("4111111111111111");
card.holderName("Juan Perez Ramirez");
card.cvv2("110");
card.expirationMonth(12);
card.expirationYear(20);
card.deviceSessionId("kR1MiQhz2otdIuUlQkbEyitIqVMiI16f");
request.card(card);

request = api.subscriptions().create("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"002"
   },
   "cancel_at_period_end":false,
   "charge_date":"2019-05-22",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2014-06-20",
   "trial_end_date":"2014-06-20",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Crear una nueva suscripción

Definición

openpayAPI.SubscriptionService.Create(string customer_id, Subscription request);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription request = new Subscription();
request.PlanId = "idPlan-01001";
request.TrialEndDate = new Datetime(2019, 5, 1);
Card card = new Card();
card.HolderName = "Juan Perez Ramirez";
card.CardNumber = "4111111111111111";
card.Cvv2 = "110";
card.ExpirationMonth = "12";
card.ExpirationYear = "20";
card.DeviceSessionId = "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f";
request.Card = card;

request = api.SubscriptionService.Create("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"002"
   },
   "cancel_at_period_end":false,
   "charge_date":"2019-05-22",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2014-06-20",
   "trial_end_date":"2014-06-20",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Actualizar una suscripción

Actualiza la información de una suscripción activa.

Petición

Propiedad	Descripción
cancel_at_period_end	*booelan* (opcional) Indica si se cancela la suscripción al terminar el periodo.
trial_end_date	*string* (opcional, longitud = 10) Último día de prueba del cliente. Si no se indica se utilizará el valor de trial_days del plan para calcularlo. Si se indica una fecha anterior al día de hoy, se interpretará como una suscripción sin días de prueba. (Con formato yyy-mm-dd)
source_id	*string* (opcional, longitud = 45) Identificador del token o la tarjeta previamente registrada al cliente con la que se cobrará la suscripción.
card	*object* (opcional) Medio de pago con el cual se cobrará la suscripción. Ver objeto tarjeta

Respuesta

Regresa el objeto suscripción actualizado o una respuesta de error si ocurrió algún problema en la actualización.

cURL

PHP

JAVA

cURL

Actualizar una suscripción

Definición

PUT https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions/{subscriptionId}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions/s0gmyor4yqtyv1miqwr0 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X PUT -d '{
  "trial_end_date": "2016-01-11",
   "card": {
        "card_number": "343434343434343",
        "holder_name": "Juan Perez Ramirez",
        "expiration_year": "20",
        "expiration_month": "12",
        "cvv2":"1234"
    }
}'

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2016-01-12",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2019-05-11",
   "trial_end_date":"2019-05-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

PHP

Actualizar una suscripción

Definición

<?
$customer = $openpay->customers->get(customerId);
$subscription = $customer->subscriptions->get(subscriptionId);
$subscription->save();
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
$subscription->trial_end_date = '2014-12-31';
$subscription->save();
?>

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2016-01-12",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2019-05-11",
   "trial_end_date":"2019-05-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

JAVA

Actualizar una suscripción

Definición

openpayAPI.subscriptions().update(Subscription request);

Ejemplo de petición

final Calendar trialEndDate = Calendar.getInstance();
trialEndDate.set(2019, 5, 1, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription request = new Subscription();
request.planId("idPlan-01001");
request.trialEndDate(trialEndDate.getTime());
request.sourceId("ktrpvymgatocelsciak7");

request = api.subscriptions().update(request);

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2016-01-12",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2019-05-11",
   "trial_end_date":"2019-05-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Actualizar una suscripción

Definición

openpayAPI.SubscriptionService.Update(string customer_id, Subscription subscription);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription request = new Subscription();
request.PlanId = "idPlan-01001";
request.TrialEndDate = new Datetime(2019, 5, 1);;
request.CardId = "ktrpvymgatocelsciak7";

request = api.SubscriptionService.Update("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"BANCO DE BOGOTÁ",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2016-01-12",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2019-05-11",
   "trial_end_date":"2019-05-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Obtener una suscripción

Obtiene los detalles de la suscripción de un cliente.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador de la suscripción

Respuesta

Regresa un objeto suscripción

cURL

PHP

JAVA

cURL

Obtener una suscripción

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions/s0gmyor4yqtyv1miqwr0 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"AMERICAN EXPRESS",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2019-05-12",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2019-05-11",
   "trial_end_date":"2019-05-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

PHP

Obtener una suscripción

Definición

<?
$customer = $openpay->customers->get(customerId);
$subscription = $customer->subscriptions->get(subscriptionId);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
?>

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"AMERICAN EXPRESS",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2019-05-12",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2019-05-11",
   "trial_end_date":"2019-05-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

JAVA

Obtener una suscripción

Definición

openpayAPI.subscriptions().get(String customerId, String customerId);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription subscription = api.subscriptions().get("a9pvykxz4g5rg0fplze0", "s0gmyor4yqtyv1miqwr0");

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"AMERICAN EXPRESS",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2019-05-12",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2019-05-11",
   "trial_end_date":"2019-05-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Obtener una suscripción

Definición

openpayAPI.SubscriptionService.Get(string customer_id, string subscription_id);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription subscription = api.SubscriptionService.Get("a9pvykxz4g5rg0fplze0", "s0gmyor4yqtyv1miqwr0");

Ejemplo de respuesta

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "bank_name":"AMERICAN EXPRESS",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2019-05-12",
   "creation_date":"2019-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2019-05-11",
   "trial_end_date":"2019-05-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Cancelar suscripción

Cancela inmediatamente la suscrupción del cliente. Ya no se realizarán mas cargos a la tarjeta y todos cargos pendientes se cancelarán.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador del plan a eliminar

Respuesta

Si la suscripción se cancelo correctamente la respuesta es vacía, si no se regresa un objeto error indicando el motivo.

cURL

PHP

JAVA

cURL

Cancelar suscripción

Definición

DELETE https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions/s0gmyor4yqtyv1miqwr0 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE

PHP

Cancelar suscripción

Definición

<?
$customer = $openpay->customers->get(customerId);
$subscription = $customer->subscriptions->get(subscriptionId);
$subscription->delete();
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
$subscription->delete();
?>

JAVA

Cancelar suscripción

Definición

openpayAPI.subscriptions().delete(String customerId, String subscriptionId);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.subscriptions().delete("a9pvykxz4g5rg0fplze0", "s0gmyor4yqtyv1miqwr0");

Cancelar suscripción

Definición

openpayAPI.SubscriptionService.Delete(string customer_id, string subscription_id);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.SubscriptionService.Delete("a9pvykxz4g5rg0fplze0", "s0gmyor4yqtyv1miqwr0");

Listado de suscripciones

Regresa los detalles de todas las suscripciones activas para un cliente en específico.

Petición

Se puede realizar búsquedas utilizando los siguiente parámetros.

Propiedad	Descripción
creation	*date* Igual a la fecha de creación. Formato yyyy-mm-dd
creation[gte]	*date* Mayor a la fecha de creación. Formato yyyy-mm-dd
creation[lte]	*date* Menor a la fecha de creación. Formato yyyy-mm-dd
offset	*numeric* Número de registros a omitir al inicio, por defecto 0.
limit	*numeric* Número de registros que se requieren, por defecto 10.

Respuesta

Listado de objetos suscripción que tiene el cliente. Ordenados por fecha de creación en orden descendente.

cURL

PHP

JAVA

cURL

Listado de suscripciones

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions

Ejemplo de petición

curl -g "https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions?limit=10" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Ejemplo de respuesta

[
   {
      "id":"s0gmyor4yqtyv1miqwr0",
      "status":"trial",
      "card":{
         "type":"credit",
         "brand":"american_express",
         "address":null,
         "card_number":"343434XXXXX4343",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"12",
         "allows_charges":true,
         "bank_name":"AMERICAN EXPRESS",
         "bank_code":"103"
      },
      "cancel_at_period_end":false,
      "charge_date":"2019-05-22",
      "creation_date":"2019-05-22T15:56:18-05:00",
      "current_period_number":0,
      "period_end_date":"2019-05-11",
      "trial_end_date":"2019-05-11",
      "plan_id":"pbi4kb8hpb64x0uud2eb",
      "customer_id":"ag4nktpdzebjiye1tlze"
   }
]

PHP

Listado de suscripciones

Definición

<?
$customer = $openpay->customers->get(customerId);
$subscriptionList = $customer->subscriptions->getList(findDataRequest);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$findData = array(
    'creation[gte]' => '2019-01-01',
    'creation[lte]' => '2019-12-31',
    'offset' => 0,
    'limit' => 5);

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscriptionList = $customer->subscriptions->getList($findData);
?>

Ejemplo de respuesta

[
   {
      "id":"s0gmyor4yqtyv1miqwr0",
      "status":"trial",
      "card":{
         "type":"credit",
         "brand":"american_express",
         "address":null,
         "card_number":"343434XXXXX4343",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"12",
         "allows_charges":true,
         "bank_name":"AMERICAN EXPRESS",
         "bank_code":"103"
      },
      "cancel_at_period_end":false,
      "charge_date":"2019-05-22",
      "creation_date":"2019-05-22T15:56:18-05:00",
      "current_period_number":0,
      "period_end_date":"2019-05-11",
      "trial_end_date":"2019-05-11",
      "plan_id":"pbi4kb8hpb64x0uud2eb",
      "customer_id":"ag4nktpdzebjiye1tlze"
   }
]

JAVA

Listado de suscripciones

Definición

openpayAPI.subscriptions().list(String customerId, SearchParams request);

Ejemplo de petición

final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2019, 1, 1, 0, 0, 0);
dateLte.set(2019, 12, 31, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<Subscription> subscriptions = api.subscriptions().list("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

[
   {
      "id":"s0gmyor4yqtyv1miqwr0",
      "status":"trial",
      "card":{
         "type":"credit",
         "brand":"american_express",
         "address":null,
         "card_number":"343434XXXXX4343",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"12",
         "allows_charges":true,
         "bank_name":"AMERICAN EXPRESS",
         "bank_code":"103"
      },
      "cancel_at_period_end":false,
      "charge_date":"2019-05-22",
      "creation_date":"2019-05-22T15:56:18-05:00",
      "current_period_number":0,
      "period_end_date":"2019-05-11",
      "trial_end_date":"2019-05-11",
      "plan_id":"pbi4kb8hpb64x0uud2eb",
      "customer_id":"ag4nktpdzebjiye1tlze"
   }
]

Listado de suscripciones

Definición

openpayAPI.SubscriptionService.List(string customer_id, SearchParams request = null);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2019, 1, 1);
request.CreationLte = new DateTime(2019, 12, 31);
request.Offset = 0;
request.Limit = 100;

List<Subscription> subscriptions = api.SubscriptionService.List("a9pvykxz4g5rg0fplze0", request);

Ejemplo de respuesta

[
   {
      "id":"s0gmyor4yqtyv1miqwr0",
      "status":"trial",
      "card":{
         "type":"credit",
         "brand":"american_express",
         "address":null,
         "card_number":"343434XXXXX4343",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"12",
         "allows_charges":true,
         "bank_name":"AMERICAN EXPRESS",
         "bank_code":"103"
      },
      "cancel_at_period_end":false,
      "charge_date":"2019-05-22",
      "creation_date":"2019-05-22T15:56:18-05:00",
      "current_period_number":0,
      "period_end_date":"2019-05-11",
      "trial_end_date":"2019-05-11",
      "plan_id":"pbi4kb8hpb64x0uud2eb",
      "customer_id":"ag4nktpdzebjiye1tlze"
   }
]

Webhooks

Estos permiten notificar al cliente cuando un evento ha sucedido en la plataforma, para que el comercio pueda tomar las acciones correspondientes.

Para que la Openpay invoque un webhook, es importante que se encuentre verificado.

Objeto Webhook

Propiedad	Descripción
id	*string* Identificador único del webhook.
url	*string* URL del webhook
user	*string* Nombre de usuario para autenticación básica del webhook.
password	*string* Contraseña para autenticación básica del webhook.
event_types	*array[string]* Listado de eventos a los que respondera el webhook.
status	*string* Estado del webhook, indica si esta verificado (verified) o no esta verificado (unverified).

Los tipos de eventos soportados son:

Evento	Categoría	Descripción
charge.refunded	Cargos	Informa cuando es reembolsado un cargo.
charge.failed	Cargos	Informa cuando un cargo fallo y no se aplico.
charge.cancelled	Cargos	Informa cuando un cargo es cancelado.
charge.created	Cargos	Informa cuando un cargo es programado.
charge.succeeded	Cargos	Informa cuando un cargo es aplicado.
charge.rescored.to.decline	Cargos	Informa cuando a un cargo le es recalculado su score y es declinado.
subscription.charge.failed	Suscripción	Informa cuando el cargo de una suscripción fallo.
payout.created	Pagos	Informa cuando un pago fue programado para el siguiente día.
payout.succeeded	Pagos	Informa cuando un pago programado se ha aplicado.
payout.failed	Pagos	Informa cuando un pago fallo.
transfer.succeeded	Transferencias	Informa cuando se realiza una transferencia entre dos cuentas Openpay.
fee.succeeded	Comisiones	Informa cuando se cobra un Fee a un Customer.
fee.refund.succeeded	Comisiones	Informa cuando se reembolsa un Fee a un Customer.
spei.received	SPEI	Informa cuando se recibe un pago por SPEI para agregar fondos a la cuenta.
chargeback.created	Contracargos	Informa cuando se recibió un chargeback de una transacción y se esta iniciando la investigación.
chargeback.rejected	Contracargos	Informa cuando un contracargo fue rechazado.
chargeback.accepted	Contracargos	Informa cuando un contracargo fue aceptado.
order.created	Orden	Informa cuando una orden es creada y programada.
order.activated	Orden	Informa cuando una orden es activada.
order.payment.received	Orden	Informa cuando el pago de una orden es recibido.
order.completed	Orden	Informa cuando una orden es completada.
order.expired	Orden	Informa cuando una orden ha expirado.
order.cancelled	Orden	Informa cuando una orden es cancelada.
order.payment.cancelled	Orden	Informa cuando el pago de una orden es cancelado.

cURL

PHP

JAVA

cURL

Objeto Webhook

Ejemplo de objeto

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "password" : "passjuanito",
    "event_types" : [
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "chargeback.accepted"
    ],
    "status":"verified"
}

PHP

Objeto Webhook

Ejemplo de objeto

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "password" : "passjuanito",
    "event_types" : [
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "chargeback.accepted"
    ],
    "status":"verified"
}

JAVA

Objeto Webhook

Ejemplo de objeto

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "password" : "passjuanito",
    "event_types" : [
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "chargeback.accepted"
    ],
    "status":"verified"
}

Objeto Webhook

Ejemplo de objeto

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "password" : "passjuanito",
    "event_types" : [
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "chargeback.accepted"
    ],
    "status":"verified"
}

Crear un Webhook

Al crear un nuevo webhook se hará una petición a la url indicada para verificar el webhook.

Al momento de guardar el webhook se generará un id que podrá ser usado para eliminar o simplemente obtener la información no sensible del webhook.

Petición

Propiedad	Descripción
url	*string* URL del webhook
user	*string* Nombre de usuario para autenticación básica del webhook.
password	*string* Contraseña para autenticación básica del webhook.
event_types	*array[string]* Listado de eventos a los que respondera el webhook.

Respuesta

Regresa un objeto webhook cuando se creó correctamente o una respuesta de error si ocurrió algún problema en la creación.

cURL

PHP

JAVA

cURL

Crear un Webhook

Definición

POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/webhooks

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/webhooks \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "password" : "passjuanito",
    "event_types" : [
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "chargeback.accepted"
    ]
}'

Ejemplo de respuesta

{
  "id" : "wkn0t30zfxpmhr5usgfa",
  "url" : "http://requestb.in/qt3bq0qt",
  "user" : "juanito",
  "event_types" : [
    "charge.succeeded",
    "charge.created",
    "charge.cancelled",
    "charge.failed"
  ],
  "status" : "verified"
}

PHP

Crear un Webhook

Definición

<?
$webhook = $openpay->webhooks->add(webhook);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$webhook = array(
    'url' => 'http://requestb.in/11vxrsf1',
    'user' => 'juanito',
    'password' => 'passjuanito',
    'event_types' => array(
      'charge.refunded',
      'charge.failed',
      'charge.cancelled',
      'charge.created',
      'chargeback.accepted'
    )
    );

$webhook = $openpay->webhooks->add($webhook);
?>

Ejemplo de respuesta

{
  "id" : "wkn0t30zfxpmhr5usgfa",
  "url" : "http://requestb.in/qt3bq0qt",
  "user" : "juanito",
  "event_types" : [
    "charge.succeeded",
    "charge.created",
    "charge.cancelled",
    "charge.failed"
  ],
  "status" : "verified"
}

JAVA

Crear un Webhook

Definición

openpayAPI.webhooks().create(Webhook request);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Webhook request = new Webhook();
request.url("http://requestb.in/11vxrsf1");
request.user("juanito");
request.password("passjuanito");
request.addEventType("charge.refunded");
request.addEventType("charge.failed");

Webhook webhook = api.webhooks().create(request);

Ejemplo de respuesta

{
  "id" : "wkn0t30zfxpmhr5usgfa",
  "url" : "http://requestb.in/qt3bq0qt",
  "user" : "juanito",
  "event_types" : [
    "charge.succeeded",
    "charge.created",
    "charge.cancelled",
    "charge.failed"
  ],
  "status" : "verified"
}

Crear un Webhook

Definición

openpayAPI.WebhooksService.Create(Webhook request);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Webhook request = new Webhook();
request.Url = "http://requestb.in/11vxrsf1";
request.User = "juanito";
request.Password = "passjuanito";
request.AddEventType("charge.refunded");
request.AddEventType("charge.failed");

Webhook webhook = api.WebhookService.Create(request);

Ejemplo de respuesta

{
  "id" : "wkn0t30zfxpmhr5usgfa",
  "url" : "http://requestb.in/qt3bq0qt",
  "user" : "juanito",
  "event_types" : [
    "charge.succeeded",
    "charge.created",
    "charge.cancelled",
    "charge.failed"
  ],
  "status" : "verified"
}

Obtener un Webhook

Obtiene los detalles de un webhook solicitándolo con su id.

Nota: Nunca se regresarán datos sensibles como son el password para accesar al webhook.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador único del webhook

Respuesta

Regresa un objeto webhook

cURL

PHP

JAVA

cURL

Obtener un Webhook

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/webhooks/{WEBHOOK_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/webhooks/wxvanstudf4ssme8khmc \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json"

Ejemplo de respuesta

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "status" : "verified"
  }

PHP

Obtener un Webhook

Definición

<?
$webhook = $openpay->webhooks->get(webhookId);
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$webhook = $openpay->webhooks->get('wxvanstudf4ssme8khmc');
?>

Ejemplo de respuesta

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "status" : "verified"
  }

JAVA

Obtener un Webhook

Definición

openpayAPI.webhooks().get(String webhookId);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Webhook webhook = api.webhooks().get("wxvanstudf4ssme8khmc");

Ejemplo de respuesta

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "status" : "verified"
  }

Obtener un Webhook

Definición

openpayAPI.WebhooksService.Get(string webhookId);

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Webhook webhook = api.WebhooksService.Get("wxvanstudf4ssme8khmc");

Ejemplo de respuesta

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "status" : "verified"
  }

Eliminar un Webhook

Elimina un webhook del comercio.

Para eliminarlo sólo es necesario proporcionar el identificador del webhook.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador único del webhook

Respuesta

Si el webhook se borra correctamente la respuesta es vacía, si no se puede borrar se regresa un objeto error indicando el motivo.

cURL

PHP

JAVA

cURL

Eliminar un Webhook

Definición

DELETE https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/webhooks/{WEBHOOK_ID}

Ejemplo de petición con cliente

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/webhooks/wxvanstudf4ssme8khmc \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE

PHP

Eliminar un Webhook

Definición

<?
$webhook = $openpay->webhooks->get(webhookId);
$webhook->delete();
?>

Ejemplo de petición con cliente

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$webhook = $openpay->webhooks->get('wxvanstudf4ssme8khmc');
$webhook->delete();
?>

JAVA

Eliminar un Webhook

Definición

openpayAPI.webhooks().delete(String webhookId);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.webhooks().delete("wxvanstudf4ssme8khmc");

Eliminar un Webhook

Definición

openpayAPI.WebhooksService.Delete(string webhook_id);

Ejemplo de petición con cliente

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.WebhooksService.Delete("wxvanstudf4ssme8khmc");

Listado de Webhook

Regresa una lista de webhooks registrados por comercio.

Nota: Nunca se regresarán datos sensibles como son el password para accesar al webhook.

Petición

Respuesta

Listado de objetos objeto webhook registrados de acuerdo a los parámetros proporcionados.

cURL

PHP

JAVA

cURL

Listado de Webhook

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/webhooks

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/webhooks \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json"

Ejemplo de respuesta

[
  {
    "id" : "wDashboard185",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "url" : "http://requestb.in/11vxrsf1",
    "status" : "verified"
  },
  {
    "id" : "wDashboard186",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed"
    ],
    "url" : "http://requestb.in/1fhpiog1",
    "status" : "verified"
  }
]

PHP

Listado de Webhook

Definición

<?
$webhookList = $openpay->webhooks->getList();
?>

Ejemplo de petición

<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac', 'CO');

$webhookList = $openpay->webhooks->getList();
?>

Ejemplo de respuesta

[
  {
    "id" : "wDashboard185",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "url" : "http://requestb.in/11vxrsf1",
    "status" : "verified"
  },
  {
    "id" : "wDashboard186",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed"
    ],
    "url" : "http://requestb.in/1fhpiog1",
    "status" : "verified"
  }
]

JAVA

Listado de Webhook

Definición

openpayAPI.webhooks().list();

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.co", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
List<Webhook> webhooks = api.webhooks().list();

Ejemplo de respuesta

[
  {
    "id" : "wDashboard185",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "url" : "http://requestb.in/11vxrsf1",
    "status" : "verified"
  },
  {
    "id" : "wDashboard186",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed"
    ],
    "url" : "http://requestb.in/1fhpiog1",
    "status" : "verified"
  }
]

Listado de Webhook

Definición

openpayAPI.WebhooksService.List();

Ejemplo de petición

OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
List<Webhook> webhooks = api.WebhooksService.List();

Ejemplo de respuesta

[
  {
    "id" : "wDashboard185",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "url" : "http://requestb.in/11vxrsf1",
    "status" : "verified"
  },
  {
    "id" : "wDashboard186",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed"
    ],
    "url" : "http://requestb.in/1fhpiog1",
    "status" : "verified"
  }
]

Tokens

El objetivo de generar tokens es que se capture la información de la tarjeta desde el navegador o dispositivo del usuario final para que dicha información no viaje a través de tu servidor y así puede evitar o reducir certificaciones PCI.

Para usar esta funcionalidad de la API, te recomendamos usar nuestra librería en JavaScript para cuando tu aplicación este en Web y nuestros SDK’s de Android o iOS para cuando este en móvil.

Características

Se crean a nivel comercio
No se ligan a ningún cliente
Después de crearse solo se puede usar una sola vez, para hacer un cargo con token

Objeto Token

Propiedad	Descripción
id	*string* Identificador del token. Esté es el que deberás usar para posteriormente hacer un cargo.
card	*object* Datos de la tarjeta asociada al token. Ver objeto tarjeta

cURL

PHP

JAVA

cURL

Objeto Token

Ejemplo de objeto

{
      "id":"tokfa4swch8gr4icy2ma",
      "card":{
         "card_number":"1111",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"04",
         "address":{
            "line1":"Av 5 de febrero",
            "line2":"Roble 207",
            "line3":"Bogota",
            "state":"Bogota",
            "city":"Bogota",
            "postal_code":"110511",
            "country_code":"CO"
         },
         "creation_date":"2014-01-30T13:53:11-06:00",
         "brand":"visa"
      }
   }

PHP

Objeto Token

Ejemplo de objeto

{
      "id":"tokfa4swch8gr4icy2ma",
      "card":{
         "card_number":"1111",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"04",
         "address":{
            "line1":"Av 5 de febrero",
            "line2":"Roble 207",
            "line3":"Bogota",
            "state":"Bogota",
            "city":"Bogota",
            "postal_code":"110511",
            "country_code":"CO"
         },
         "creation_date":"2014-01-30T13:53:11-06:00",
         "brand":"visa"
      }
   }

JAVA

Objeto Token

Ejemplo de objeto

{
      "id":"tokfa4swch8gr4icy2ma",
      "card":{
         "card_number":"1111",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"04",
         "address":{
            "line1":"Av 5 de febrero",
            "line2":"Roble 207",
            "line3":"Bogota",
            "state":"Bogota",
            "city":"Bogota",
            "postal_code":"110511",
            "country_code":"CO"
         },
         "creation_date":"2014-01-30T13:53:11-06:00",
         "brand":"visa"
      }
   }

Objeto Token

Ejemplo de objeto

{
      "id":"tokfa4swch8gr4icy2ma",
      "card":{
         "card_number":"1111",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"04",
         "address":{
            "line1":"Av 5 de febrero",
            "line2":"Roble 207",
            "line3":"Bogota",
            "state":"Bogota",
            "city":"Bogota",
            "postal_code":"110511",
            "country_code":"CO"
         },
         "creation_date":"2014-01-30T13:53:11-06:00",
         "brand":"visa"
      }
   }

Crear un nuevo token

Para la creación de un token en Openpay es necesario enviar el objeto con la información a registrar. Una vez guardado el token no se puede obtener el número y código de seguridad ya que esta información es encriptada.

Petición

Propiedad	Descripción
holder_name	*string* (requerido) Nombre del tarjeta habiente.
card_number	*numeric* (requerido) Numero de tarjeta puede ser de 16 o 19 dígitos.
cvv2	*numeric* (requerido) Código de seguridad como aparece en la parte de atrás de la tarjeta. Generalmente 3 dígitos.
expiration_month	*numeric* (requerido) Mes de expiración tal como aparece en la tarjeta.
expiration_year	*numeric* (requerido) Año de expiración tal como aparece en la tarjeta.
address	*object* (opcional) Dirección de facturación del tarjeta habiente.

Repuesta

Regresa el objeto token creado o una respuesta de error si ocurrió algún problema en la creación.

cURL

PHP

JAVA

cURL

Crear un nuevo token

Definición

POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/tokens

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/tokens \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X POST -d '{
   "card_number":"4111111111111111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "cvv2":"110",
   "address":{
      "city":"Bogotá",
      "country_code":"CO",
      "postal_code":"110511",
      "line1":"Av 5 de Febrero",
      "line2":"Roble 207",
      "line3":"col carrillo",
      "state":"Bogota"
   }
}'

Ejemplo de respuesta

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Bogota",
         "city":"Bogotá",
         "postal_code":"110511",
         "country_code":"CO"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

PHP

Crear un nuevo token

Definición

POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/tokens

Ejemplo de petición

Ejemplo de respuesta

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Bogota",
         "city":"Bogotá",
         "postal_code":"110511",
         "country_code":"CO"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

JAVA

Crear un nuevo token

Definición

POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/tokens

Ejemplo de petición

Ejemplo de respuesta

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Bogota",
         "city":"Bogotá",
         "postal_code":"110511",
         "country_code":"CO"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

Crear un nuevo token

Definición

POST https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/tokens

Ejemplo de petición

Ejemplo de respuesta

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Bogota",
         "city":"Bogotá",
         "postal_code":"110511",
         "country_code":"CO"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

Obtener un token

Obtiene los detalles de un token. Es necesario tener el id.

Nota: Nunca se regresarán datos sensibles como son el código de seguridad y del número de tarjeta.

Petición

Propiedad	Descripción
id	*string* (requerido, longitud = 45) Identificador de token.

Respuesta

Regresa un objeto token

cURL

PHP

JAVA

cURL

Obtener un token

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/tokens/{TOKEN_ID}

Ejemplo de petición

curl https://sandbox-api.openpay.co/v1/mzdtln0bmtms6o3kck8f/tokens/k1n0mscnjwhxqia8q7cm \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Ejemplo de respuesta

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Bogota",
         "city":"Bogotá",
         "postal_code":"110511",
         "country_code":"CO"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

PHP

Obtener un token

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/tokens/{TOKEN_ID}

Ejemplo de petición

Ejemplo de respuesta

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Bogota",
         "city":"Bogotá",
         "postal_code":"110511",
         "country_code":"CO"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

JAVA

Obtener un token

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/tokens/{TOKEN_ID}

Ejemplo de petición

Ejemplo de respuesta

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Bogota",
         "city":"Bogotá",
         "postal_code":"110511",
         "country_code":"CO"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

Obtener un token

Definición

GET https://sandbox-api.openpay.co/v1/{MERCHANT_ID}/tokens/{TOKEN_ID}

Ejemplo de petición

Ejemplo de respuesta

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Bogota",
         "city":"Bogotá",
         "postal_code":"110511",
         "country_code":"CO"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

Tiendas

El objeto representa una tienda de conveniencia

Objeto Tienda

Propiedad	Descripción
id_store	*string* Identificador único asignado al momento de su creación.
id	*string* Identificador único por cadena.
name	*datetime* Nombre de la tienda.
last_update	*string* Fecha de la ultima actualizacion de la tienda en formato ISO 8601.
geolocation	*objeto* <br/Representacion geografica de la tienda por medio de coordenadas, Latitud y Longitud.
address	*objeto* Direccion de la tienda.
paynet_chain	*objeto* Cadena paynet a la que pertence.

cURL

PHP

JAVA

cURL

Objeto Tienda

Ejemplo de Objeto

{
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110111",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "/logotipos/extra.png",
      "thumb": "/thumb/extra.png",
      "max_amount": 99999.99
    }
  }

PHP

Objeto Tienda

Ejemplo de Objeto

{
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110111",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "/logotipos/extra.png",
      "thumb": "/thumb/extra.png",
      "max_amount": 99999.99
    }
  }

JAVA

Objeto Tienda

Ejemplo de Objeto

{
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110111",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "/logotipos/extra.png",
      "thumb": "/thumb/extra.png",
      "max_amount": 99999.99
    }
  }

Objeto Tienda

Ejemplo de Objeto

{
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110111",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "/logotipos/extra.png",
      "thumb": "/thumb/extra.png",
      "max_amount": 99999.99
    }
  }

Obtener lista de tiendas por ubicación

Obtiene los detalles la cuenta del comercio. Solo se requiere indicar el id unico del comercio que se quiere obtener.

Petición

Propiedad	Descripción
latitud	*numeric* (requerido) Latitud de la ubicacion geografica de la tienda
longitud	*numeric* (requerido) Longitud de la ubicacion geografica de la tienda
kilometers	*numeric* (requerido) Distancia del radio de la busqueda en kilometros
amount	*numeric* (requerido) Monto de la compra

Respuesta

Si se encuentran tiendas cerca del rango se devolverá un arreglo con las tiendas encontradas.

cURL

PHP

JAVA

cURL

Obtener lista de tiendas por ubicación

Definición

GET https://api.openpay.co/stores?latitud={latitud}&longitud={longitud}&kilometers={radio}&amount={monto}

Ejemplo de petición

curl https://api.openpay.co/stores?latitud=20.618975&longitud=-100.422290&kilometers=1.5&amount=4000 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Ejemplo de respuesta

[
  {
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110111",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "/logotipos/extra.png",
      "thumb": "/thumb/extra.png",
      "max_amount": 99999.99
    }
  },
  {
    "id_store": 4726,
    "id": 68,
    "name": "ASTURIANO TECNOLOGICO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.410136,
      "lat": 20.61632,
      "place_id": "EktQcm9sIFRlY25vbMOzZ2ljbyBOdGUgOTk5LCBTYW4gUGFibG8sIFNhbnRpYWdvIGRlIFF1ZXLDqXRhcm8sIFFyby4sIE3DqXhpY28"
    },
    "address": {
      "line1": "PROLONGACION TECNOLOGICO NORTE #999",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110311",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EL ASTURIANO",
      "logo": "/logotipos/asturiano.png",
      "thumb": "/thumb/asturiano.png",
      "max_amount": 99999.99
    }
  }
]

PHP

Obtener lista de tiendas por ubicación

Definición

<?
// =============================
// Funcionalidad no implementada
// =============================
?>

Ejemplo de petición

Ejemplo de respuesta

[
  {
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110111",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "/logotipos/extra.png",
      "thumb": "/thumb/extra.png",
      "max_amount": 99999.99
    }
  },
  {
    "id_store": 4726,
    "id": 68,
    "name": "ASTURIANO TECNOLOGICO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.410136,
      "lat": 20.61632,
      "place_id": "EktQcm9sIFRlY25vbMOzZ2ljbyBOdGUgOTk5LCBTYW4gUGFibG8sIFNhbnRpYWdvIGRlIFF1ZXLDqXRhcm8sIFFyby4sIE3DqXhpY28"
    },
    "address": {
      "line1": "PROLONGACION TECNOLOGICO NORTE #999",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110311",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EL ASTURIANO",
      "logo": "/logotipos/asturiano.png",
      "thumb": "/thumb/asturiano.png",
      "max_amount": 99999.99
    }
  }
]

JAVA

Obtener lista de tiendas por ubicación

Definición

// =============================
// Funcionalidad no implementada
// =============================

Ejemplo de petición

Ejemplo de respuesta

[
  {
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110111",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "/logotipos/extra.png",
      "thumb": "/thumb/extra.png",
      "max_amount": 99999.99
    }
  },
  {
    "id_store": 4726,
    "id": 68,
    "name": "ASTURIANO TECNOLOGICO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.410136,
      "lat": 20.61632,
      "place_id": "EktQcm9sIFRlY25vbMOzZ2ljbyBOdGUgOTk5LCBTYW4gUGFibG8sIFNhbnRpYWdvIGRlIFF1ZXLDqXRhcm8sIFFyby4sIE3DqXhpY28"
    },
    "address": {
      "line1": "PROLONGACION TECNOLOGICO NORTE #999",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110311",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EL ASTURIANO",
      "logo": "/logotipos/asturiano.png",
      "thumb": "/thumb/asturiano.png",
      "max_amount": 99999.99
    }
  }
]

Obtener lista de tiendas por ubicación

Definición

// =============================
// Funcionalidad no implementada
// =============================

Ejemplo de petición

Ejemplo de respuesta

[
  {
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110111",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "/logotipos/extra.png",
      "thumb": "/thumb/extra.png",
      "max_amount": 99999.99
    }
  },
  {
    "id_store": 4726,
    "id": 68,
    "name": "ASTURIANO TECNOLOGICO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.410136,
      "lat": 20.61632,
      "place_id": "EktQcm9sIFRlY25vbMOzZ2ljbyBOdGUgOTk5LCBTYW4gUGFibG8sIFNhbnRpYWdvIGRlIFF1ZXLDqXRhcm8sIFFyby4sIE3DqXhpY28"
    },
    "address": {
      "line1": "PROLONGACION TECNOLOGICO NORTE #999",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "BOGOTA",
      "city": "BOGOTA",
      "postal_code": "110311",
      "country_code": "CO"
    },
    "paynet_chain": {
      "name": "EL ASTURIANO",
      "logo": "/logotipos/asturiano.png",
      "thumb": "/thumb/asturiano.png",
      "max_amount": 99999.99
    }
  }
]

Objetos Comunes

Información de objetos compartidos en peticiones y respuestas.

Objeto Transacción

Propiedad	Descripción
id	string Identificador único asignado por Openpay al momento de su creación.
authorization	*string* Número de autorización generado por el procesador.
transaction_type	*string* Tipo de transacción que fue creada: fee, charge, payout, transfer.
operation_type	*string* Tipo de afectación en la cuenta: in, out.
method	*string* Tipo de método usado en la transacción: card, bank o customer.
creation_date	*datetime* Fecha de creación de la transacción en formato ISO 8601.
order_id	*string* Referencia única o número de orden/transacción.
status	*string* Estatus actual de la transacción. Posibles valores: completed, in_progress, failed.
amount	*numeric* Cantidad de la transacción a dos decimales.
description	*string* Descripción de la transacción.
error_message	*string* Si la transacción está en status: failed, en este campo se mostrará la razón del fallo.
customer_id	*string* Identificar único del cliente al cual pertence la transacción. Si es valor es nulo, la transacción pertenece a la cuenta del comercio.
currency	*string* Moneda usada en la operación, por default es COP.
bank_account	*objeto* Datos de la cuenta bancaria usada en la transacción. Ver objeto BankAccoount
card	*objeto* Datos de la tarjeta usada en la transacción. Ver objeto Card

cURL

PHP

JAVA

cURL

Objeto Transacción

Ejemplo de Objeto

{
    "id": "tryqbk08mmjihwejd3si",
    "authorization": "faa33f71-f122-4efc-9",
    "operation_type": "in",
    "method": "bank_account",
    "transaction_type": "charge",
    "status": "completed",
    "conciliated": true,
    "creation_date": "2018-10-19T11:14:33-05:00",
    "operation_date": "2018-10-19T11:14:45-05:00",
    "description": "1 Calzado M",
    "error_message": null,
    "order_id": "161951571501672795",
    "customer_id": "azxhcjwagajxtfciuytw",
    "due_date": "2019-10-18T11:34:33-05:00",
    "amount": 54627.00,
    "currency": "COP",
    "payment_method": {
        "type": "redirect",
        "url": "https://myecommerce.co/shopping-cart/"
    }
}

PHP

Objeto Transacción

Ejemplo de Objeto

{
    "id": "tryqbk08mmjihwejd3si",
    "authorization": "faa33f71-f122-4efc-9",
    "operation_type": "in",
    "method": "bank_account",
    "transaction_type": "charge",
    "status": "completed",
    "conciliated": true,
    "creation_date": "2018-10-19T11:14:33-05:00",
    "operation_date": "2018-10-19T11:14:45-05:00",
    "description": "1 Calzado M",
    "error_message": null,
    "order_id": "161951571501672795",
    "customer_id": "azxhcjwagajxtfciuytw",
    "due_date": "2019-10-18T11:34:33-05:00",
    "amount": 54627.00,
    "currency": "COP",
    "payment_method": {
        "type": "redirect",
        "url": "https://myecommerce.co/shopping-cart/"
    }
}

JAVA

Objeto Transacción

Ejemplo de Objeto

{
    "id": "tryqbk08mmjihwejd3si",
    "authorization": "faa33f71-f122-4efc-9",
    "operation_type": "in",
    "method": "bank_account",
    "transaction_type": "charge",
    "status": "completed",
    "conciliated": true,
    "creation_date": "2018-10-19T11:14:33-05:00",
    "operation_date": "2018-10-19T11:14:45-05:00",
    "description": "1 Calzado M",
    "error_message": null,
    "order_id": "161951571501672795",
    "customer_id": "azxhcjwagajxtfciuytw",
    "due_date": "2019-10-18T11:34:33-05:00",
    "amount": 54627.00,
    "currency": "COP",
    "payment_method": {
        "type": "redirect",
        "url": "https://myecommerce.co/shopping-cart/"
    }
}

Objeto Transacción

Ejemplo de Objeto

{
    "id": "tryqbk08mmjihwejd3si",
    "authorization": "faa33f71-f122-4efc-9",
    "operation_type": "in",
    "method": "bank_account",
    "transaction_type": "charge",
    "status": "completed",
    "conciliated": true,
    "creation_date": "2018-10-19T11:14:33-05:00",
    "operation_date": "2018-10-19T11:14:45-05:00",
    "description": "1 Calzado M",
    "error_message": null,
    "order_id": "161951571501672795",
    "customer_id": "azxhcjwagajxtfciuytw",
    "due_date": "2019-10-18T11:34:33-05:00",
    "amount": 54627.00,
    "currency": "COP",
    "payment_method": {
        "type": "redirect",
        "url": "https://myecommerce.co/shopping-cart/"
    }
}

Objeto Dirección Cliente

Propiedad	Descripción
department	*string* (requerido) Departamento.
city	*string* (requerido) Ciudad.
additional	*string* (requerido) Información adicional para especificar la dirección.

cURL

PHP

JAVA

cURL

Objeto Dirección Cliente

Ejemplo de Objeto

{
   "department":"Medellín",
   "city":"Antioquia",
   "additional":"Avenida 7g bis #229-32 Apartamento 511"
{
    "id": "trpfgkjvusju7u0tssmk",
    "authorization": null,
    "operation_type": "in",
    "transaction_type": "charge",
    "status": "in_progress",
    "conciliated": false,
    "iva": "1900",
    "creation_date": "2020-06-29T13:27:58-05:00",
    "operation_date": "2020-06-29T13:27:58-05:00",
    "description": "Cargo inicial a mi cuenta",
    "error_message": null,
    "order_id": "oid-12345",
    "due_date": "2020-06-29T13:47:58-05:00",
    "payment_method": {
        "type": "redirect",
        "url": "https://qa-api.openpay.co/v1/mr0w3azn2utpnldvgxkk/charges/trpfgkjvusju7u0tssmk/pse_capture"
    },
    "currency": "COP",
    "amount": 10000.00,
    "customer": {
        "name": "Cliente Colombia",
        "last_name": "Vazquez Juarez",
        "email": "juan.vazquez@empresa.co",
        "phone_number": "4448936475",
        "address": null,
        "creation_date": "2020-06-29T13:27:58-05:00",
        "external_id": null,
        "customer_address": {
            "department": "Medellín",
            "city": "Antioquía",
            "additional": "Avenida 7m bis #174-25 Apartamento 637",
            "country": "CO"
        },
        "clabe": null
    },
    "method": "bank_account"
}

PHP

Objeto Dirección Cliente

Ejemplo de Objeto

{
   "department":"Medellín",
   "city":"Antioquia",
   "additional":"Avenida 7g bis #229-32 Apartamento 511"
}

JAVA

Objeto Dirección Cliente

Ejemplo de Objeto

{
   "department":"Medellín",
   "city":"Antioquia",
   "additional":"Avenida 7g bis #229-32 Apartamento 511"
}

Objeto Dirección Cliente

Ejemplo de Objeto

{
   "department":"Medellín",
   "city":"Antioquia",
   "additional":"Avenida 7g bis #229-32 Apartamento 511"
}

Objeto Estatus Transacción

Value	Description
IN_PROGRESS	Transacción en proceso
COMPLETED	Transacción ejecutadá correctamente
REFUNDED	Transacción reembolsada
CHARGEBACK_PENDING	Transacción con contracargo pendiente
CHARGEBACK_ACCEPTED	Transacción con contracargo aceptado
CHARGEBACK_ADJUSTMENT	Transacción con ajuste de contracargo
CHARGE_PENDING	Transacción de cargo que no ha sido pagada
CANCELLED	Transacción de cargo que no fue pagada y se ha cancelado
FAILED	Transacción que se intentó pagar pero ocurrió algún error

Notificaciones

23 julio, 202413 mayo, 2020 por user

Notificaciones

¿Qué es un Webhook?

Los Webhooks te permiten recibir notificaciones de las transacciones realizadas a algún servicio web que tu configures en tu cuenta. Esto te permite saber, por ejemplo, cuando se ha realizado un cargo a una tarjeta o cuando un depósito se ha realizado con éxito.

Nota: Si deseas manejar los webhooks vía API, consulta la referencia aquí

Objeto Webhook

Cada vez que se realice una transacción, Openpay enviará una objecto JSON a las URL’s registradas para recibir webhooks. Openpay puede agregar mas campos en un futuro, o agregar nuevos valores a campos existentes, por lo que es recomendado que tu Webhook pueda manejar datos adicionales desconocidos.

Parámetros

El objeto webhook contiene los siguientes datos:

Campo	Descripción
type	string El tipo de evento que generó la notificación
event_date	timestamp Fecha de creación del evento en formato ISO 8601
transaction	string El objeto de Transacción relacionado con el evento. No enviado en notificaciones de tipo verification.
verification_code	string El código de verificación del Webhook. Enviado solamente en notificaciones de tipo verification.

Todas las notificaciones de las transacciones se enviarán a las URL’s que tengas registradas. Para distinguir una transacción, utiliza la propiedad type

Nota: Openpay intentará entregar la notificación hasta recibir una respuesta de éxito. Esto puede causar que algunas notificaciones se envíen dos veces, por lo que debes estar preparado para poder recibir la misma notificación mas de una vez.

Ejemplo:

{
    "type" : "charge.succeeded",
    "event_date" : "2013-11-22T15:09:38-06:00",
    "transaction" : {
        "amount" : 2000.0,
        "authorization" : "801585",
        "method" : "card",
        "operation_type" : "in",
        "transaction_type" : "charge",
        "card" : {
            "type" : "debit",
            "brand" : "mastercard",
            "address" : {
               "line1" : "Calle #1 Interior #2",
               "line2" : null,
               "line3" : null,
               "state" : "Queretaro",
               "city" : "Queretaro",
               "postal_code" : "76040",
               "country_code" : "MX"
            },
            "card_number" : "1881",
            "holder_name" : "Card Holder",
            "expiration_month" : "10",
            "expiration_year" : "14",
            "allows_charges" : true,
            "allows_payouts" : true,
            "creation_date" : "2013-11-22T15:09:32-06:00",
            "bank_name" : "BBVA BANCOMER",
            "bank_code" : "012"
        },
        "status" : "completed",
        "id" : "tlxcm4vprtz74qoenuay",
        "creation_date" : "2013-11-22T15:09:33-06:00",
        "description" : "Description",
        "error_message" : null,
        "order_id" : "oid_14235"
    }
}

Características de un servicio Webhook válido

Endpoint: Solo dominios (No IPs). ejemplo: https://notifications.merchant.com
Puerto: 443/TCP, 1518/TCP, 1519/TCP, 8443/TCP y 10443/TCP
Protocolo: HTTPS/TLS_1.2
Certificado: Válido (firmado por CA pública y match con dominio).

Tipos

Tipo	Descripción
verification	La notificación contiene el código de verificación del Webhook
charge.created	Se creó un cargo para ser pagado por transferencia bancaria.
charge.succeeded	Indica que el cargo se ha completado (tarjeta, banco o tienda)
charge.refunded	Un cargo a tarjeta fue reembolzado.
payout.created	Se ha programado un pago.
payout.succeeded	Se ha enviado el pago.
payout.failed	El pago fue rechazado.
transfer.succeeded	Se ha realizado una transferencia entre dos clientes.
fee.succeeded	Se ha cobrado una comisión a un cliente.
spei.received	Se han agregado fondos a una cuenta mediante SPEI.
chargeback.created	Se ha recibido un contracargo de un cargo a tarjeta
chargeback.rejected	El contrcargo se ha ganado a favor del comercio
chargeback.accepted	El contracargo se ha perdido. Se ha creado una transacción tipo contracargo que descontará los fondos de tu cuenta.

Tu servidor debe estar preparado para aceptar notificaciones de tipos no conocidos, para asegurar una compatibilidad con futuras versiones.

Registro

Para configurar un Webhook sigue los siguientes pasos:

Entra al Dashboard de Openpay utilizando tu correo y tu contraseña
Da click en tu nombre para accesar a tu perfil de comercio.
En la sección de Webhooks, selecciona la opción +Agregar Webhook.
En el formulario que aparece, indica la URL completa de tu webhook, incluyendo el protocolo a usar. Es recomendado utilizar https.
Si tu Webhook requiere autenticación HTTP, configurala. Actualmente solo se soporta autenticación HTTP Basic.
Da click en el botón Guardar.

Verificación

Al terminar la configuración de registro, Openpay enviará mediante POST un mensaje JSON a la URL indicada, conteniendo un objeto de notificación Webhook. Tu servicio deberá guardar el código de verificación de alguna manera, y regresar el estado 200 OK.

Si por alguna razón requieres que se te envíe de nuevo el código de verificación, selecciona la opción Reenviar Código. Un nuevo código de verificación será generado y enviado a la URL proporcionada.

Una vez que ya tengas el código de verificación del Webhook, selecciona la opción de Verificar e introduce el código proporcionado en el objeto de la notificación. Esto activará el Webhook en Openpay, y empezarás a recibir notificaciones de las transacciones realizadas a partir de ese momento.

Ejemplo:

{
    "type" : "verification",
    "event_date" : "2013-11-22T11:04:49-06:00",
    "verification_code" : "UY1qqrxw"
}

Implementación

Para implementar tu Webhook, solo tienes que crear un servicio Web con una URL a la que Openpay pueda enviar peticiones POST.

Tu Webhook debe manejar los diferentes tipos de notificaciones, incluyendo recibir el código de verificación, para que puedas darlo de alta en Openpay.

Tu Webhook también deberá poder recibir tipos de notificaciones inesperados, para asegurar compatibilidad con futuras versiones.

Los Webhook deberán regresar un estado HTTP 200 OK siempre que reciban una notificación, de otra manera Openpay reintentará el envío continuamente.

Eliminación

En cualquier momento puedes seleccionar la opción -Eliminar desde el dashboard para eliminar un Webhook y dejar de recibir notificaciones a esa URL.

Contenido

Pruebas

23 julio, 202413 mayo, 2020 por user

Pruebas

Contamos con un ambiente de pruebas (sandbox) preparado para simular los diferentes casos de éxito y error al momento de procesar tus operaciones.

Para comenzar a probar, verifica lo siguiente:

Contar con tus llaves para poder invocar a la API. Si vas a usar el cliente javascript debes de usar tu llave pública, en otro caso debes de usar tu llave privada.
Usar datos de prueba para números de tarjeta, códigos de seguridad cvv2 y fechas de expiración.
Manejar de manera adecuada los errores que el API puede regresar.
Si usas Webhooks, verifica que tu implementación esta lista para recibir los mensajes que la plataforma Openpay te envía.

Mientras estas en tu fase de pruebas, te recomendamos ingresar al dashboard desde el que podrás consultar la siguiente información:

Llaves de acceso publica y privada así como tus datos de registro en general.
Registros de todas tus operaciones (transacciones).
Registros de todas tus peticiones independientemente de si son operaciones de cargos y pagos u operaciones administrativas.

Cargos con token / Redireccionamiento / 3D Secure / Teléfono (IVR)

Números de tarjeta válidos

Para la simulacion de cargos con tarjeta, te proporcionamos lo siguientes numeros validos:

Numero de tarjeta	Marca	Banco emisor
4111111111111111	Visa	BANAMEX
4242424242424242	Visa	BANCO DE COLOMBIA
5555555555554444	MasterCard	BANCO SANTANDER SERFIN (Acepta pago con puntos)
5105105105105100	MasterCard	SCOTIABANK (Acepta pago con puntos)
345678000000007	AmericanExpress	AMERICAN EXPRESS
341111111111111	AmericanExpress	AMERICAN EXPRESS
343434343434343	AmericanExpress	AMERICAN EXPRESS
5062541600005232	Carnet
5064050100000063	Carnet
5064510000300020	Carnet

Nota: Si intentas hacer un cargo con cualquier otro numero de tarjeta, el sistema te regresara un codigo de error.

Fechas de vigencia y códigos de seguridad válidos.

Pueden ser cualquiera solo se tiene que usar una fecha de vigencia mayor al mes actual y cualquier código de seguridad de 3 dígitos para VISA,MASTERCARD y uno de 4 dígitos para AMEX

Números de tarjeta no válidos**

Con el fin de que puedas simular el mayor número de casos de error, te proporcionamos los siguientes números de tarjeta:

Número de tarjeta	Error	Descripción
4222222222222220	3001	La tarjeta fue rechazada.
4000000000000069	3002	La tarjeta ha expirado.
4444444444444448	3003	La tarjeta no tiene fondos suficientes.
4000000000000119	3004	La tarjeta ha sido identificada como una tarjeta robada.
4000000000000044	3005	La tarjeta ha sido rechazada por el sistema antifraudes.
5454545454545454	3005	La tarjeta ha sido rechazada por el sistema antifraudes.
340000000000009	3001	La tarjeta fue rechazada.
373737373737374	3002	La tarjeta ha expirado.
370000000000002	3003	La tarjeta no tiene fondos suficientes.

OneClick y/o Suscripciones

En el ambiente de sandbox todas las operaciones son simuladas, por lo que solo podrás guardar los siguientes números de tarjeta:

Número de tarjeta	Marca	Banco emisor	Tipo
4111111111111111	Visa	BANAMEX	Débito
4242424242424242	Visa	BANCO DE COLOMBIA	Crédito
5555555555554444	MasterCard	BANCO SANTANDER SERFIN	Débito
5105105105105100	MasterCard	SCOTIABANK	Crédito
4444444444444448	Visa	BANCO MERCANTIL DEL NORTE	Crédito
345678000000007	AmericanExpress	AMERICAN EXPRESS	Crédito
341111111111111	AmericanExpress	AMERICAN EXPRESS	Crédito
343434343434343	AmericanExpress	AMERICAN EXPRESS	Crédito
370000000000002	AmericanExpress	AMERICAN EXPRESS	Crédito

Nota: Cualquier otra tarjeta que intentes dar de alta, el sistema te regresara un codigo de error.

Autenticación selectiva

Número de tarjeta	Marca	Banco emisor	Tipo
5454545454545454.	MasterCard	HSBC	Crédito

Nota: Esta tarjeta será aprobada en un cargo con 3D Secure, en cualquier otra modalida será rechazada por la herramienta antifraude.

Webhooks

Si tienes configurados Webhooks, no tienes que hacer nada mas que tener listo tu sitio para empezar a recibir notificaciones.

El ambiente de sandbox esta preparado para enviar las notificaciones tal como si se tratará de un ambiente productivo.

Contenido

Openpay.js

23 julio, 202412 mayo, 2020 por user

Introducción

¿Qué es Openpay.js?

Openpay.js es una librería Javascript diseñada para facilitar la creación de tokens en base a datos de tarjetas de crédito y débito desde una página web sin la necesidad que la información del alta pase por el servidor origen (El servidor del comercio).

Ventajas:

Es seguro, la información de la tarjeta no tiene que pasar por el servidor origen, sino que es enviada directamente a Openpay.
Es la manera más rápida y sencilla para integrar nuestro módulo de cobros en tu página web.

Primeros pasos

El primer paso para la integración consiste en agregar la librería Openpay.js a tu página como se ve a continuación:

<script type="text/javascript" src="https://resources.openpay.co/openpay.v1.min.js"></script>

Configuración

Para poder utilizar Openpay.js es necesario que se configuren tanto el ID de comercio, como la llave pública que te fueron asignados cuando creaste tu cuenta en el dashboard del ambiente de sandbox. Con estos datos, Openpay podrá identificar tus operaciones y podrá asignar tus tarjetas y cobros.

La configuración de ambos datos se hace con los métodos OpenPay.setId() y OpenPay.setApiKey(), respectivamente:

OpenPay.setId('MERCHANT_ID'); 
OpenPay.setApiKey('PUBLIC_API_KEY');

Nota: Tanto el MERCHANT-ID como el PUBLIC_API_KEY, los puedes consultar en el dashboard al entrar en tu cuenta de openpay, en la página de inicio o en la página de tu perfil.

Recuerda: Nunca debes utilizar tu llave privada con está librería, debido a que la llave es visible del lado del cliente.

Habilitar modo sandbox

Para que pruebes tu implementación, existe el ambiente de sandbox, el cual se habilita con el método: OpenPay.setSandboxMode().

OpenPay.setSandboxMode(FLAG);

El parámetro FLAG es una bandera true/false para activar o desactivar el modo de pruebas.

Si es necesario, se puede utilizar el método OpenPay.getSandboxMode() para determinar el estatus del modo sandbox en cualquier momento:

OpenPay.getSandboxMode(); // TRUE/FALSE, dependiendo si el modo está activado o no.

Nota: El ambiente de sandbox tiene las mismas funcionalidades que producción, pero solo permite el uso de ciertos números de tarjeta, elegidos con el fines de probar, mas información en la sección de pruebas.

Creación tokens sin formulario

Una vez que instalaste y configuraste la librería, para crear un token es necesario llamar al método OpenPay.token.create()

OpenPay.token.create(CREATE_PARAMETERS_OBJECT, SUCCESS_CALLBACK, ERROR_CALLBACK);

Los parámetros que recibe el método son:

El parámetro CREATE_PARAMETERS_OBJECT es un objeto Javascript que contiene la información de la tarjeta.
El parámetro SUCCESS_CALLBACK definen la función que se llamarán en caso de que la operación haya sido exitosa.
El parámetro ERROR_CALLBACK definen la función que se llamarán en caso de que la operación haya fallado.

Ejemplo de creación de token:

OpenPay.token.create({
      "card_number":"4111111111111111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "cvv2":"110",
      "address":{
         "city":"Bogotá",
         "line3":"Bogotá",
         "postal_code":"76900",
         "line1":"Carrera Bulnes No. 1027",
         "line2":"Roble 207",
         "state":"Bogotá",
         "country_code":"CO"
      }
}, onSuccess, onError);

El método regresa un objeto tipo token del cual necesitaras posteriormente el id del token. La definición del objeto token la encontrarás aquí.

Creación de tokens con formulario

La librería Openpay.js te facilita la extracción de la información de la tarjeta desde formulario para su posterior envió por medio del método OpenPay.token.extractFormAndCreate()

OpenPay.token.extractFormAndCreate(CREATE_FORM_OBJECT, SUCCESS_CALLBACK, ERROR_CALLBACK);

Los parámetros que recibe el método son:

El parámetro CREATE_FORM_OBJECT es un objeto tipo form que contiene la información de la tarjeta.
El parámetro SUCCESS_CALLBACK definen la función que se llamarán en caso de que la operación haya sido correcta.
El parámetro ERROR_CALLBACK definen la función que se llamarán en caso de que la operación haya fallado.

Para empezar a crear tokens, es necesario tener un formulario como este:

<form id="processCard" name="processCard">
    <p>Holder Name:</p><input data-openpay-card="holder_name" size="50" type="text">
    <p>Card number:</p><input data-openpay-card="card_number" size="50" type="text">
    <p>Expiration year:</p><input data-openpay-card="expiration_year" size="4" type="text">
    <p>Expiration month:</p><input data-openpay-card="expiration_month" size="4" type="text">
    <p>cvv2:</p><input data-openpay-card="cvv2" size="5" type="text">
    <p>Street:</p><input data-openpay-card-address="line1" size="20" type="text">
    <p>Number:</p><input data-openpay-card-address="line2" size="20" type="text">
    <p>References:</p><input data-openpay-card-address="line3" size="20" type="text">
    <p>Postal code:</p><input data-openpay-card-address="postal_code" size="6" type="text">
    <p>City:</p><input data-openpay-card-address="city" size="20" type="text">
    <p>State:</p><input data-openpay-card-address="state" size="20" type="text">
    <p>Country code:</p><input data-openpay-card-address="country_code" size="3" type="text">
    <input id="makeRequestCard" type="button" value="Make Card">
</form>

Nota: Lo mas importante es agregar los atributos data-openpay-card y data-openpay-card-address en los inputs donde se captura la información de la tarjeta y la dirección respectivamente, ya que así el método sabe que valores tomar.

Posteriormente al momento de generar el token, hacer una invocacion al metodo token.extractFormAndCreate(), como se muestra a continuación

OpenPay.token.extractFormAndCreate(
      $('#processCard'), 
      successCard, 
      errorCard, 
      _customerId);

El método regresa un objeto tipo token del cual necesitaras posteriormente el id del token. La definición del objeto token la encontrarás aquí.

Para ver un ejemplo descarga la página de ejemplo desde el sitio de github: openpay-js

Manejo de respuestas

Las funciones de respuesta son para manejar el resultado de las operaciones. Son funciones simples de Javascript pero que reciben como argumento un objeto tipo respuesta.

Los campos del objeto de respuesta se describen a continuación

Campo	Formato	Descripción
status	Integer	Describe el status HTTP de la operación. En caso de que se produzca un error antes de enviar la petición, el status será igual a cero. En caso de éxito es 200.
message	String	Solo se presenta en casos de error. Descripción corta del error que ha ocurrido. Puede ser uno de los siguientes valores: “Unknown error”, “Request error”, “Response error (Unknown final status)”, “Empty or invalid OpenPay ID”, “Empty or invalid API Key”, “Browser error”, “Timeout after X milliseconds”.
data	Objeto	Contiene un Objeto Error con la información del error en la transacción proporcionada por el servidor de OpenPay. En caso de éxito contiene un objeto tipo token.

Notas: Aunque las funciones de respuesta son opcionales, recomendamos que se implementen para que el resultado de la transacción pueda ser monitoreado en la página web.

En caso de éxito: SuccessCallback

Esta función es llamada cuando la operación fue exitosa de principio a fin. Recibe un solo parámetro que es un objeto Javascript con los datos del token.

Ejemplo completo de implementación de una función SuccessCallback:

function SuccessCallback(response) {
	alert('Operación exitosa');
	var content = '', results = document.getElementById('resultDetail');
	content .= 'Id tarjeta: ' + response.data.id+ '<br/>';
	content .= 'A nombre de: ' + response.data.holder_name + '<br/>';
	content .= 'Marca de tarjeta usada: ' + response.data.brand + '<br/>';
	results.innerHTML = content;
}

En caso de error: ErrorCallback

Esta función se ejecutará cada vez que una operación haya fallado (por cualquier circunstancia, antes o después de enviar la petición). Al igual que el SuccessCallback(), recibe un solo parámetro que es un objeto Javascript con el detalle del fallo.

Ejemplo completo de implementación de una función ErrorCallback:

function ErrorCallback(response) {
    alert('Fallo en la transacción');
    var content = '', results = document.getElementById('resultDetail');
    content .= 'Estatus del error: ' + response.data.status + '<br />';
    content .= 'Error: ' + response.message + '<br />';
    content .= 'Descripción: ' + response.data.description + '<br />';
    content .= 'ID de la petición: ' + response.data.request_id + '<br />';
    results.innerHTML = content;
}

Tipos de error

Además del campo status que guarda el estado de la transacción, es posible determinar el error que haya sucedido por medio del campo message. El mensaje puede ser uno de los siguientes:

Empty or invalid OpenPay ID: Sucede cuando no se ha configurado correctamente el ID de usuario con el método OpenPay.setId()
Empty or invalid API Key: Al igual que el error anterior, sucede cuando no se ha configurado el API Key con el método OpenPay.setApiKey()
Browser error: Es disparado cuando hay un error en el navegador que impide que la petición se realice correctamente. Puede provocarse por caracterísiticas que son necesarias para ejecutar cierto código y que están faltantes en el navegador. Para mayor información consulta la sección “Compatibilidad y requerimientos”.
Request error: Este error indica que hubo un error en el servidor de Openpay. Puede deberse a parámetros faltantes, formatos u algún otro problema que impide realizar correctamente la transacción.
Response error (Unknown final status): Cuando se genera este error, quiere decir que la petición de transacción fue enviada correctamente al servidor de Openpay pero no se recibió ninguna respuesta. Es posible que esto se deba a un problema en Openpay. Para mayor información contacta a OpenPay.
Timeout after X milliseconds: Se lanza cuando la petición ha tardado mucho tiempo en ejecutarse y, por tanto, expira el tiempo de respuesta.
Unknown error: Se genera cuando existe algún error desconocido que impide que la petición se realice. Puede ser por problemas en el navegador o de conectividad.

Funciones de validación

Además de las funciones para procesar cargos por tarjeta, Openpay.js también incluye algunas funciones para validad los principales datos que son necesarios para llevar a cabo la transacción, sobre todo los referentes a los números de tarjeta.

Los métodos disponibles son:

OpenPay.card.validateCardNumber()
OpenPay.card.validateCVC()
OpenPay.card.validateExpiry()
OpenPay.card.cardType()

Validación de número de tarjeta

Para realizar la validación de un número de tarjeta es posible utilizar el método OpenPay.card.validateCardNumber().

Este método recibe como parámetro un String con el número de tarjeta que se validará y regresar un true/false en caso de que se trate de un número de tarjeta válido y sea aceptado por Openpay. Ejemplo:

OpenPay.card.validateCardNumber('5555555555554444');

Este método es muy útil para determinar si un número de tarjeta es válido y si es candidato para utilizarse con Openpay, por eso recomendamos que se use sistemáticamente antes de intentar un cobro con tarjeta.

Ejemplos:

OpenPay.card.validateCardNumber('5555555555554444');
// TRUE. Número de tarjeta válido y aceptado por OpenPay (MASTERCARD)
OpenPay.card.validateCardNumber('378282246310005');
// FALSE. Número de tarjeta válido pero no aceptado por OpenPay (AMEX)

Validación de Código de Seguridad

Para validar un código de seguridad se utiliza el método OpenPay.card.validateCVC().

Este método recibe como parámetro un String y devuelve true/false en caso de que la cadena sea válida.

Ejemplos:

OpenPay.card.validateCVC('123'); // válido
OpenPay.card.validateCVC('1234'); // válido
OpenPay.card.validateCVC('A23'); // inválido

Adicionalmente, el código de seguridad se puede validar pasando como segundo parámetro el núemro de la tarjeta, para determinar si el código es válido para el tipo de tarjeta en cuestión.

Ejemplos:

OpenPay.card.validateCVC('123','5555555555554444'); 
// válido, tarjeta MASTERCARD y CVC de longitud 3
OpenPay.card.validateCVC('1234','5555555555554444'); 
// inválido, tarjeta MASTERCARD y CVC de longitud 4
OpenPay.card.validateCVC('123','378282246310005'); 
// inválido, tarjeta AMERICAN EXPRESS y CVC de longitud 3
OpenPay.card.validateCVC('1234','378282246310005'); 
// válido, tarjeta AMERICAN EXPRESS y CVC de longitud 4

Validación de fecha de expiración

Para este propósito se utiliza el método OpenPay.card.validateExpiry().

Recibe como parámetros dos Strings que representan el mes y año de expiración de la tarjeta. Devuelve true/false cuando la combinación de ambos datos, mes y año, determinan una fecha de expiración válida. Ejemplo:

OpenPay.card.validateExpiry('01', '2013'); // inválido
OpenPay.card.validateExpiry('05', '2015'); // válido

Validación del tipo de tarjeta

Es posible determinar (en la mayoría de las veces,) el tipo de tarjeta al que pertenece un número de tarjeta. Para eso, se utiliza el método OpenPay.card.cardType().

El método recibe como parámetro un número de tarjeta y devuelve un String con el nombre del tipo de tarjeta.

Ejemplos:

OpenPay.card.cardType('5555555555554444'); // Mastercard
OpenPay.card.cardType('4111111111111111'); // Visa
OpenPay.card.cardType('4917300800000000'); // Visa Electron
OpenPay.card.cardType('378282246310005'); // American Express
OpenPay.card.cardType('30569309025904'); // Diners Club Carte Blanche
OpenPay.card.cardType('6011111111111117'); // Discover
OpenPay.card.cardType('3530111333300000'); // JCB

Compatibilidad y requerimientos

Para utilizar Openpay.js es necesario contar con uno de los siguientes navegadores:

Chrome 29.0+
Firefox 23.0+
Safari 5.1+
Opera 17.0+
iOS Safari 4.0+
Android Browser 2.1+
Blackberry Browser 7.0+
IE Mobile 10.0

Notas: Aunque las funciones de respuesta son opcionales, recomendamos que se implementen para que el resultado de la transacción pueda ser monitoreado en la página web.

Contenido

Antifraudes

31 enero, 202512 mayo, 2020 por user

Anti-Fraudes

Preguntas generales

¿Qué es la herramienta antifraudes?

Es la herramienta que Openpay proporcionan para la prevención de fraudes en cargos a tarjetas y se proporciona a todos los comercios registrados en Openpay por medio de la implementación de la librería openpay-data.js sin cargos extra por su uso.

¿Como funciona?

Una vez implementada la librería openpay-data.js en su página web o la librería de android/iOS, en cada transacción de cargo con tarjeta se aplicarán una series de reglas para saber si la transacción es fraudulenta o legítima. Todo el proceso se lleva a cabo en cuestión de milisegundos, haciéndolo casi invisible para sus clientes.

El avanzado conjunto de reglas que filtran las transacciones verifican varios factores incluyendo el número de tarjeta de crédito/débito, dirección de la tarjeta, correo electrónico e información del dispositivo de donde se está realizando el cargo.

¿Como la empiezo a usar?

Se tiene que implementar el uso de una librería de JavaScript si las transacciones de cargo son realizadas desde una página web. Si las transacciones son desde un dispositivo movil puede hacer uso de nuestros SDK’s para implementarla.

¿Que me responde el API cuando una transacción es marcada como fraudulenta?

En este caso el API responderá un objeto de error con los siguientes datos.

Respuesta:

{
    "category": "gateway",
    "description": "The card was declined by fraud system",
    "http_code": 402,
    "error_code": 3005,
    "request_id": "4fc452d8-5ddc-4464-ae70-e03569622850"
}

¿Que puedo hacer si quiero que una transacción marcada como fraudulenta sea aprobada? No hay otra opción mas que decirle al cliente que vuelva a intentar el cargo con información de otra tarjeta.

Implementación con JavaScript

1.- Carga e inicialización

Con el siguiente código se carga la librería y se inicializar el valor para el device_session_id:

<script type='text/javascript' src="https://resources.openpay.co/openpay-data.v1.min.js"></script>
<script type="text/javascript">
  var deviceSessionId = OpenPay.deviceData.setup("formId", "deviceIdHiddenFieldName");
</script>

Nota: openpay-data.js depende de la libreria openpay.js. Cuida ejecutar primero el metodo setSandboxMode() de la libreria openpay.js y despues el metodo setup.

El parámetro formId, recibe el id del formulario que contiene la información del cargo que se enviara a tu servidor. Indica a la librería que en ese formulario es donde se va a agregar un campo oculto con el valor del device_session_id.

El parámetro deviceIdHiddenFieldName, recibe el nombre del campo oculto donde se asignara el device_session_id. Este dato es importante si piensas recuperar el valor del hidden y enviar mediante un submit.

Otra forma de manejar el valor del device_session_id es almacenarlo en una variable y posteriormente adjuntarlo a alguna petición tipo ajax. Este proceso es manual:

<script type='text/javascript' src="https://resources.openpay.co/openpay-data.v1.min.js""></script>
<script type="text/javascript">
  var deviceSessionId = OpenPay.deviceData.setup();
</script>

2.- Manejo del lado del servidor

Cada vez que alguien entra en tu página o sitio, se recolectaran de forma transparente datos del dispositivo desde donde este accediendo, y se genera el device_session_id. Una vez que tu cliente realiza el cargo con tarjeta, asegurate de enviar a tu servidor, como parte de los datos de la transacción, el device_session_id.

Una vez que los datos hayan llegado a tu servidor, envia el device_session_id como parte de la petición a los servidores de openpay, como se muestra a continuación:

<?php
$openpay = Openpay::getInstance('merchant_id', 'private_key');

$chargeData = array(
    'method' => 'card',
    'source_id' => $_POST["source_id"],
    'amount' => (float)$_POST["amount"],
    'currency' => $_POST["currency"],
    'description' => $_POST["description"],
    'order_id' => 'ORDEN-00071',
    'device_session_id' => $_POST["deviceIdHiddenFieldName"]
);

$charge = $openpay->charges->create($chargeData);
?>

Para ver un ejemplo completo de como hacer un cargo, revisa el tutorial de cargos.

Implementación en Android

Descarga e instalación de la librería en: https://github.com/open-pay/openpay-android

La libreria openpay-android, permite usar la herramienta anti-fraudes de dos formas diferentes. La primera es usando la implementación que se proporciona por defecto y la segunda es creando una implementación propia. A continuación veremos como.

Antes de usar la herramienta anti-fraude desde tu proyecto android, es necesario que habilites los siguientes permisos en el archivo AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" ></uses-permission>

1.- Carga e inicialización

Usando la implementación del StatusListener por defecto, con el siguiente código se carga la librería y se inicializar el valor para el device_session_id:

Openpay openpay = new Openpay("MERCHANT_ID", "PUBLIC_API_KEY", productionMode);
String deviceSessionId = openpay.getDeviceCollectorDefaultImpl()
    .setup(this.getActivity());

Nota El método setup requiere que se pase el activity desde el que se esta invocando. En caso de que se invoque desde un fragment, se puede recuperar el objeto activity invocando el método fragment.getActivity().

2.- Manejo del lado del servidor

Al momento de procesar el pago desde el dispositivo android, asegúrese de mandar a sus servidores el device_session_id y posteriormente enviarlo como parte de la invocación a nuestra api.

CreateCardChargeParams charge = new CreateCardChargeParams()
                .cardId(this.registeredCard.getId())
                .amount(amount)
		.currency(currency)
                .description(desc)
                .orderId(orderId)
                .capture(false)
                .deviceSessionId(deviceSessionId);
        Charge transaction = this.api.charges().create(charge);

Parámetros adicionales

a) Configuración de timeout

long millis=300000; //5 min
openpay.getDeviceCollectorDefaultImpl().setCancelSetupTime(millis);

b) Obtener Errores

String errors = openpay.getDeviceCollectorDefaultImpl().getErrorMessage();
Log.d(this.getClass().getName(), errors);

Implementación en iOS

Descarga e instalación de la librería en: https://github.com/open-pay/openpay-ios

1.- Carga e inicialización

Crear una instancia de la clase Openpay y llamar al método createDeviceSessionId

Openpay *openpayAPI = [[Openpay alloc] initWithMerchantId:MERCHANT_ID
                                                   apyKey:API_KEY
                                         isProductionMode:NO];

NSString *sessionId= [openpayAPI createDeviceSessionId];

Nota Crea la variable de Openpay a nivel de la clase y no a nivel de método.

Contenido

Ver la página de errores para mas información del formato del objeto de error.

Errores

23 julio, 202412 mayo, 2020 por user

Errores

Openpay siempre regresa objetos de JSON en las respuestas del servicio, incluso en caso de errores por lo que cuando exista un error recibirás el siguinte objeto error.

Objeto Error

Campo	Tipo	Descripción
category	string	La categoria general del error. request: Indica un error causado por datos enviados por el cliente. Por ejemplo, una petición inválida, un intento de una transacción sin fondos, o una transferencia a una cuenta que no existe. internal: Indica un error del lado de Openpay, y ocurrira muy raramente. gateway: Indica un error durante la transacción de los fondos de una tarjeta a la cuenta de Openpay o de la cuenta hacia un banco o tarjeta.
error_code	numeric	El código del error de Openpay indicando el problema que ocurrió.
description	string	El detalle del error.
http_code	string	Código de error HTTP de la respuesta.
request_id	string	Identificador de la petición.

Ejemplo:

{
    "category" : "request",
    "description" : "The customer with id 'm4hqp35pswl02mmc567' does not exist",
    "http_code" : 404,
    "error_code" : 1005,
    "request_id" : "1981cdb8-19cb-4bad-8256-e95d58bc035c"
}

Códigos de Error

Generales

Código	Error HTTP	Mensaje	Causa
1000	500 Internal Server Error	Internal server error, contact support	Ocurrió un error interno en el servidor de Openpay
1001	400 Bad Request	Bad Request	El formato de la petición no es JSON, los campos no tienen el formato correcto, o la petición no tiene campos que son requeridos.
1002	401 Unauthorized	The api key or merchant id are invalid	La llamada no esta autenticada o la autenticación es incorrecta.
1003	422 Unprocessable Entity	Parameters look valid but request failed	La operación no se pudo completar por que el valor de uno o más de los parametros no es correcto.
1004	503 Service Unavailable	The resource is unavailable at this moment. Please try again later	Un servicio necesario para el procesamiento de la transacción no se encuentra disponible.
1005	404 Not Found	The requested resource doesn’t exist	Uno de los recursos requeridos no existe.
1006	409 Conflict	The order_id has already been processed	Ya existe una transacción con el mismo ID de orden.
1007	402 Payment Required	Operation rejected by processor	La transferencia de fondos entre una cuenta de banco o tarjeta y la cuenta de Openpay no fue aceptada.
1008	423 Locked	The account is inactive	The account is inactive
1009	413 Request Entity too large	The request is too large	El cuerpo de la petición es demasiado grande.
1010	403 Forbidden	Method not allowed for public API key, use private key instead	Se esta utilizando la llave pública para hacer una llamada que requiere la llave privada, o bien, se esta usando la llave privada desde JavaScript.
1011	404 Not Found	The resource was previously deleted	Se solicita un recurso que esta marcado como eliminado.
1012	412 Precondition failed	The transaction amount exceeds your allowed transaction limit	El monto transacción esta fuera de los limites permitidos.
1013	412 Precondition failed	The operation is not allowed on the resource	La operación no esta permitida para el recurso.
1014	401 Unauthorized	Your account is inactive, please contact to soporte@openpay.mx for more information	La cuenta esta inactiva.
1015	504 Gateway timeout	Could not get any response from gateway. Please try again later	No se ha obtenido respuesta de la solicitud realizada al servicio.
1016	409 Conflict	The merchant email has been already processed	El mail del comercio ya ha sido procesada.
1017	502 Bad Gateway	The payment gateway is not available at the moment, please try again later	El gateway no se encuentra disponible en ese momento.
1018	402 Payment Required	The number of retries of charge is greater than allowed	El número de intentos de cargo es mayor al permitido.
1020	400 Bad Request	The number of decimal digits is not valid for this currency	El número de dígitos decimales es inválido para esta moneda

Almacenamiento

Código	Error HTTP	Mensaje	Causa
2001	409 Conflict	The bank account already exists	La cuenta de banco con esta CLABE ya se encuentra registrada en el cliente.
2003	409 Conflict	The external_id already exists	El cliente con este identificador externo (External ID) ya existe.
2004	422 Unprocessable Entity	The card number verification digit is invalid	El dígito verificador del número de tarjeta es inválido de acuerdo al algoritmo Luhn.
2005	400 Bad Request	The expiration date has expired	La fecha de expiración de la tarjeta es anterior a la fecha actual.
2006	400 Bad Request	The CVV2 security code is required	El código de seguridad de la tarjeta (CVV2) no fue proporcionado.
2007	412 Precondition Failed	The card number is only valid in sandbox	El número de tarjeta es de prueba, solamente puede usarse en Sandbox.
2008	412 Precondition Failed	The card is not valid for points	La tarjeta no es valida para puntos Santander.
2009	412 Precondition Failed	The CVV2 security code is invalid	El código de seguridad de la tarjeta (CVV2) es inválido.
2010	402 Payment Required	3D Secure authentication failed	Autenticación 3D Secure fallida.
2011	422 Unprocessable Entity	Card product type not supported	Tipo de tarjeta no soportada

Tarjetas

Código	Error HTTP	Mensaje	Causa
3001	402 Payment Required	The card was declined by the bank	La tarjeta fue declinada por el banco.
3002	402 Payment Required	The card has expired	La tarjeta ha expirado.
3003	402 Payment Required	The card doesn’t have sufficient funds	La tarjeta no tiene fondos suficientes.
3004	402 Payment Required	The card was reported as stolen	La tarjeta ha sido identificada como una tarjeta robada.
3005	402 Payment Required	Fraud risk detected by anti-fraud system — Found in blacklist	La tarjeta ha sido rechazada por el sistema antifraude. — Rechazada por coincidir con registros en lista negra.
3006	412 Precondition Failed	Request not allowed	La operación no esta permitida para este cliente o esta transacción.
3009	402 Payment Required	The card was reported as lost	La tarjeta fue reportada como perdida.
3010	402 Payment Required	The bank has restricted the card	El banco ha restringido la tarjeta.
3011	402 Payment Required	The bank has requested the card to be retained	El banco ha solicitado que la tarjeta sea retenida. Contacte al banco.
3012	412 Precondition Failed	Bank authorization is required for this charge	Se requiere solicitar al banco autorización para realizar este pago.
3201	Merchant not authorized to use payment plan	Merchant not authorized to use payment plan	El número de afiliación no soporta pago a meses sin intereses.
3203	Invalid promotion for such card type	Invalid promotion for such card type	Promoción no válida para este tipo de tarjetas.
3204	Transaction amount is less than minimum for promotion	Transaction amount is less than minimum for promotion	El monto de la transacción es menor al mínimo permitido para esta promoción.
3205	El monto de la transacción es menor al mínimo permitido para esta promoción.	Promotion not allowed	Promoción no permitida.

Cuentas

Código	Error HTTP	Mensaje	Causa
4001	412 Preconditon Failed	There are not enough funds in the openpay account	La cuenta de Openpay no tiene fondos suficientes.
4002	412 Preconditon Failed	The operation can’t be completed until pending fees are paid	La operación no puede ser completada hasta que sean pagadas las comisiones pendientes.

Webhooks

Código	Error HTTP	Mensaje	Causa
6001	409 Conflict	The webhook has already been processed	El webhook ya ha sido procesado.
6002	412 Preconditon Failed	Could not connect with webhook service, verify URL	No se ha podido conectar con el servicio de webhook.
6003	502 Bad Gateway	Service responded with an error on this moment. Please try again later	El servicio respondio con errores.

Contenido

Clientes

23 julio, 202412 mayo, 2020 por user

Clientes

Con la finalidad de cubrir las necesidades de varios de nuestros clientes Openpay cuenta con dos opciones de manejo de clientes, la elección del modo dependerá de las necesidades del negocio pues a partir del tipo de cliente, el manejo de los saldos de los clientes y del comercio se afectan de manera diferente, como se explica a continuación.

Clientes con cuenta

Un cliente con cuenta o saldo significa que si se realiza un cargo desde el cliente, el dinero se almacena en su cuenta y el propio cliente puede disponer de este para realizar transferencias o pagos, este esquema es útil para modelos de negocio donde el cliente final mantiene un saldo y puede realizar operaciones dentro de su sitio o aplicación.

Clientes tipo catálogo

Un cliente tipo catálogo dentro de Openpay únicamente sirve para registrar los datos del cliente que realizo la transacción pero el dinero siempre es enviado a la cuenta del comercio. Este esquema se recomienda para los modelos donde al cliente se realizan cobros y el dinero siempre se administra desde la cuenta del comercio.

Tabla de diferencias

A continuación se muestra una tabla comparativa de las diferencias en las operaciones para clientes con saldo y clientes sin saldo.

Funcionalidad	Cliente con cuenta	Cliente tipo catálogo
Consulta	Mantiene la información de cliente completa.	No contiene información sobre el saldo (balance) ni estado (status)
Tarjetas y cuentas bancarias	El cliente puede tener tarjetas y cuentas bancarias	El cliente puede tener tarjetas y cuentas bancarias
Cargos (tarjeta, tienda y banco)	* Afecta el saldo del cliente * La transacción se liga al cliente * La transacción puede consultarse sólo desde el cliente	* Afecta al saldo del comercio * La transacción se liga al comercio y al cliente * La transacción puede consultarse desde el cliente o comercio
Pagos	Puede realizar pagos disponiendo del saldo en su cuenta	No se permite debido a que no dispone de saldo
Transferencias	Puede realizar transferencias a otros cliente disponiendo del saldo	No se permite debido a que no dispone de saldo
Comisiones	Se pueden cobrar comisiones de su saldo	No se permite debido a que no dispone de saldo
Suscripciones	Las transacciones generadas del cobro por suscripciones solo pueden consultarse desde el comercio	Las transacciones generadas del cobro por suscripciones se pueden consultar desde el comercio o desde el cliente