PayREST (v1.5.0-12cbcf3)

Download OpenAPI specification:Download

En este documento se detalla el funcionamiento de los diferentes endpoints de la API de PayREST.

Authentication

ApiKey

Autenticación de aplicaciones utilizando la API Key asociada a cada aplicación de la plataforma.

Security Scheme Type	API Key
Header parameter name:	X-Auth-Token

Oauth2

Autenticación de usuario a través del servidor OAuth2 de Ipglobal.

Security Scheme Type	OAuth2
password OAuth Flow	Token URL: https://keycloak.ipgestion.com/auth/realms/production/protocol/openid-connect/token Scopes:

Aplicaciones

La entidad aplicación hace referencia a cada una de las aplicaciones clientes que se conectarán a la API de PayREST.

En esta sección se detallarán los endpoints utilizados para la gestión de dichas aplicaciones.

Ten en cuenta que las siguientes entidades están asociadas a una aplicación en concreto (y que por lo tanto no se podrán gestionar desde otra aplicación):

Configuraciones de pasarelas de pago
Pagos
Webhooks

Listado

Devuelve el listado completo de aplicaciones dadas de alta opcionalmente filtradas por nombre.

Authorizations:

Oauth2

query Parameters

limit	integer >= 1 Default: 10 Número de elementos a mostrar por página.
offset	integer >= 0 Default: 0 Posición del primer elemento a mostrar.
sort	string Default: "id_asc" Campo y dirección de la ordenación de los resultados. El formato debe ser: field1_direction,field2_direction Donde: `fieldN`: Representa cualquiera de los campos de la entidad (devueltos en la respuesta). `direction`: Representa la dirección de ordenación, solo pudiendo ser esta `asc` o `desc`. Nota: En caso de no indicar `direction` para alguno de los campos se usará `asc`.
name	string Nombre que se utilizará para filtrar las aplicaciones.

Responses

200

Petición correcta.

get /application

https://api.payrest.com/application

Response samples

Content type

application/json

Copy

Expand all Collapse all


[
{"links": 
[
{"href": "https://example.org/application/1",
"rel": "self"
}
],
"id": 1,
"name": "Example App",
"logo": "https://example.org/application-logo.png",
"url": "https://example.org",
"apiKey": 
{"key": "APPLICATION_API_KEY"
},
"gatewayConfigs": 
[
{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0
}
]
}
]

Creación

Permite crear una nueva aplicación, devolviendo a su vez los datos completos de la misma si la petición es correcta (como por ejemplo el ID o la API Key asociada).

Authorizations:

Oauth2

Request Body schema: application/json

Datos para la creación de la aplicación.

application

object (Application_Form)

Responses

201

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

post /application

https://api.payrest.com/application

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"application": 
{"name": "string",
"url": "string",
"logo": "string"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1",
"rel": "self"
}
],
"id": 1,
"name": "Example App",
"logo": "https://example.org/application-logo.png",
"url": "https://example.org",
"apiKey": 
{"key": "APPLICATION_API_KEY"
},
"gatewayConfigs": 
[
{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}
]
}

Detalle

Información detallada sobre una aplicación concreta.

Authorizations:

Oauth2

path Parameters

required

integer \d+

Identificador único de la aplicación.

Responses

200

Solicitud correcta.

404

No se ha encontrado ninguna aplicación con los datos proporcionados.

get /application/{id}

https://api.payrest.com/application/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1",
"rel": "self"
}
],
"id": 1,
"name": "Example App",
"logo": "https://example.org/application-logo.png",
"url": "https://example.org",
"apiKey": 
{"key": "APPLICATION_API_KEY"
},
"gatewayConfigs": 
[
{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}
]
}

Edición

Edición de la aplicación indicada. Los campos que no se encuentren en la petición se establecerán a null.

Authorizations:

Oauth2

path Parameters

required

integer \d+

Identificador único de la aplicación.

Request Body schema: application/json

Datos para la creación de la aplicación.

application

object (Application_Form)

Responses

200

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

404

No se ha encontrado ninguna aplicación con los datos proporcionados.

put /application/{id}

https://api.payrest.com/application/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"application": 
{"name": "string",
"url": "string",
"logo": "string"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1",
"rel": "self"
}
],
"id": 1,
"name": "Example App",
"logo": "https://example.org/application-logo.png",
"url": "https://example.org",
"apiKey": 
{"key": "APPLICATION_API_KEY"
},
"gatewayConfigs": 
[
{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}
]
}

Edición

Edición de la aplicación indicada. Solo se modificarán los campos que aparezcan explícitamente en la petición.

Authorizations:

Oauth2

path Parameters

required

integer \d+

Identificador único de la aplicación.

Request Body schema: application/json

Datos para la creación de la aplicación.

application

object (Application_Form)

Responses

200

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

404

No se ha encontrado ninguna aplicación con los datos proporcionados.

patch /application/{id}

https://api.payrest.com/application/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"application": 
{"name": "string",
"url": "string",
"logo": "string"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1",
"rel": "self"
}
],
"id": 1,
"name": "Example App",
"logo": "https://example.org/application-logo.png",
"url": "https://example.org",
"apiKey": 
{"key": "APPLICATION_API_KEY"
},
"gatewayConfigs": 
[
{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}
]
}

Borrado

Borra la aplicación y todos los datos asociados con la misma.

Nota: Solo es posible borrar una aplicación si esta no tiene ningún pago asociado a la misma.

Authorizations:

Oauth2

path Parameters

required

integer \d+

Identificador único de la aplicación.

Responses

204

Aplicación borrada correctamente.

400

Imposible borrar la aplicación debido a que la misma ya tiene pagos asociados.

404

No se ha encontrado ninguna aplicación con los datos proporcionados.

delete /application/{id}

https://api.payrest.com/application/{id}

Renovación de API Key

Permite renovar la API Key de una aplicación, invalidando la actual para futuros usos y generando una completamente nueva.

¡Cuidado! Esto provocará que cualquier aplicación utilizando esta API Key deje de funcionar hasta que se actualice con la nueva clave.

Authorizations:

Oauth2

path Parameters

required

integer \d+

Identificador único de la aplicación.

Responses

201

Solucitud correcta.

404

No se ha encontrado ninguna aplicación con los datos proporcionados.

post /application/{id}/recreate-key

https://api.payrest.com/application/{id}/recreate-key

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1",
"rel": "self"
}
],
"id": 1,
"name": "Example App",
"logo": "https://example.org/application-logo.png",
"url": "https://example.org",
"apiKey": 
{"key": "APPLICATION_API_KEY"
},
"gatewayConfigs": 
[
{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}
]
}

Pasarelas de pago

Las pasarelas de pago son las diferentes configuraciones para los servicios de pago con los que se integra PayREST (Redsýs, PayPal, etc).

En esta sección se detallarán los endpoints utilizados para gestionar una instancia de configuración de pasarela de pago concreta.

Nota: Las pasarelas de pago estarán siempre asociadas a una aplicación concreta, por lo que todas las rutas incluirán el parámetro obligatorio applicationId.

Listado

Devuelve el listado completo de pasarelas de pago configuradas para una aplicación concreta.

Authorizations:

ApiKeyOauth2

path Parameters

applicationId

required

integer \d+

Identificador único de la aplicación.

query Parameters

limit	integer >= 1 Default: 10 Número de elementos a mostrar por página.
offset	integer >= 0 Default: 0 Posición del primer elemento a mostrar.
sort	string Default: "id_asc" Campo y dirección de la ordenación de los resultados. El formato debe ser: field1_direction,field2_direction Donde: `fieldN`: Representa cualquiera de los campos de la entidad (devueltos en la respuesta). `direction`: Representa la dirección de ordenación, solo pudiendo ser esta `asc` o `desc`. Nota: En caso de no indicar `direction` para alguno de los campos se usará `asc`.
filter	string Campo de filtro para el listado. El filtro se realizará por los campos: `id`, `name`, `gateway` y `code`.

Responses

200

Petición correcta.

404

No existe ninguna aplicación con el ID recibido.

get /application/{applicationId}/gateway

https://api.payrest.com/application/{applicationId}/gateway

Response samples

Content type

application/json

Copy

Expand all Collapse all


[
{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}
]

Creación

Permite crear una nueva pasarela de pago, devolviendo a su vez los datos completos de la misma si la petición es correcta.

Nota: Para saber qué opciones de configuración acepta un servicio de pagos concreto puedes consultar sus datos con los endpoints de la sección Servicios de pago.

Authorizations:

Oauth2

path Parameters

applicationId

required

integer \d+

Identificador único de la aplicación.

Request Body schema: application/json

Datos para la creación de la pasarela.

gatewayConfig

object (Instance_Form)

Responses

201

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

404

No existe ninguna aplicación con el ID recibido.

post /application/{applicationId}/gateway

https://api.payrest.com/application/{applicationId}/gateway

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"gatewayConfig": 
{"name": "FooInstance",
"gateway": "paypal_express_checkout",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
},
"weight": 0
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}

Detalle

Información detallada sobre una pasarela de pago concreta.

Authorizations:

ApiKeyOauth2

path Parameters

id required	integer \d+ Identificador único de la pasarela.
applicationId required	integer \d+ Identificador único de la aplicación.

Responses

200

Solicitud correcta.

404

No existe ninguna aplicación o ninguna pasarela de pago con el ID recibido.

get /application/{applicationId}/gateway/{id}

https://api.payrest.com/application/{applicationId}/gateway/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}

Edición

Edición de una pasarela de pago. Los campos que no se encuentren en la petición se establecerán a null.

Authorizations:

Oauth2

path Parameters

id required	integer \d+ Identificador único de la pasarela.
applicationId required	integer \d+ Identificador único de la aplicación.

Request Body schema: application/json

Datos para la edición de la pasarela.

gatewayConfig

object (Instance_Form)

Responses

200

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

404

No existe ninguna aplicación o ninguna pasarela de pago con el ID recibido.

put /application/{applicationId}/gateway/{id}

https://api.payrest.com/application/{applicationId}/gateway/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"gatewayConfig": 
{"name": "FooInstance",
"gateway": "paypal_express_checkout",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
},
"weight": 0
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}

Edición

Edición de una pasarela de pago. Solo se modificarán los campos que aparezca explícitamente en la petición.

Authorizations:

Oauth2

path Parameters

id required	integer \d+ Identificador único de la pasarela.
applicationId required	integer \d+ Identificador único de la aplicación.

Request Body schema: application/json

Datos para la edición de la pasarela.

gatewayConfig

object (Instance_Form)

Responses

200

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

404

No existe ninguna aplicación o ninguna pasarela de pago con el ID recibido.

patch /application/{applicationId}/gateway/{id}

https://api.payrest.com/application/{applicationId}/gateway/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"gatewayConfig": 
{"name": "FooInstance",
"gateway": "paypal_express_checkout",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
},
"weight": 0
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0,
"code": "8aad7287-4d47-4c58-bca4-285506033c98",
"config": 
{"sandbox": true,
"username": "PAYPAL_USERNAME",
"password": "PAYPAL_PASSWORD",
"signature": "PAYPAL_SIGNATURE"
}
}

Borrado

Borra la pasarela de pago y todos los datos asociados con la misma.

Authorizations:

Oauth2

path Parameters

id required	integer \d+ Identificador único de la pasarela.
applicationId required	integer \d+ Identificador único de la aplicación.

Responses

204

Pasarela de pago borrada correctamente.

400

No es posible borrar esta pasarela de pago.

404

No existe ninguna aplicación o ninguna pasarela de pago con el ID recibido.

delete /application/{applicationId}/gateway/{id}

https://api.payrest.com/application/{applicationId}/gateway/{id}

Pagos

Los pagos son las entidades que representan cada una de las transacciones creadas para una aplicación.

En esta sección se detallarán los endpoints utilizados para gestionar un pago durante su vida completa, desde su creación a su posterior pago o cancelación por parte del usuario final.

Nota: Los pagos estarán siempre asociados a una aplicación concreta, por lo que todas las rutas incluirán el parámetro obligatorio applicationId.

Listado

Devuelve el listado completo de pagos para una aplicación.

Authorizations:

ApiKeyOauth2

path Parameters

applicationId

required

integer \d+

Identificador único de la aplicación a la que pertenece el pago.

query Parameters

limit	integer >= 1 Default: 10 Número de elementos a mostrar por página.
offset	integer >= 0 Default: 0 Posición del primer elemento a mostrar.
sort	string Default: "id_asc" Campo y dirección de la ordenación de los resultados. El formato debe ser: field1_direction,field2_direction Donde: `fieldN`: Representa cualquiera de los campos de la entidad (devueltos en la respuesta). `direction`: Representa la dirección de ordenación, solo pudiendo ser esta `asc` o `desc`. Nota: En caso de no indicar `direction` para alguno de los campos se usará `asc`.
status	string Estado de los pagos por el que filtrar el listado.
client_id	string ID de cliente por el que filtrar el listado.
transaction_id	string ID de transacción asociado al pago.

Responses

200

Solicitud correcta.

404

No se ha encontrado ninguna aplicación con el ID recibido.

get /application/{applicationId}/payment

https://api.payrest.com/application/{applicationId}/payment

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1/payment/1",
"rel": "self"
}
],
"id": 1,
"currency": "EUR",
"amount": "100",
"description": "Visita guiada",
"clientId": "ID_CLIENT_1",
"clientEmail": "client@example.com",
"status": "completed",
"createdAt": "2019-02-20T12:51:16+01:00",
"flags": 
["CANCELABLE",
"CHARGEABLE"
],
"transactionId": "V8dps1gIPVLs588PI",
"type": "Simple.",
"parentId": 0,
"completionDate": "2019-02-20T12:52:16+01:00",
"askForClientDetails": "false",
"gatewayConfigs": 
[{ }
],
"subscription": 
{"links": 
[
{"href": "https://example.org/application/1/subscription/1",
"rel": "self"
}
],
"id": 1,
"currency": "EUR",
"amount": "100",
"description": "Plan Premium",
"clientId": "CLIENT_ID_1",
"clientEmail": "client@example.com",
"status": "authorized",
"urlOk": "https://example.com/ok",
"urlKo": "https://example.com/ko",
"createdAt": "2020-02-10T12:13:26+01:00",
"transactionId": "V8dps1gIPVLs588PI",
"paymentCount": 12
}
}

Creación

Crea un nuevo pago a partir de la petición enviada por el cliente.

Authorizations:

ApiKeyOauth2

path Parameters

applicationId

required

integer \d+

Identificador único de la aplicación a la que pertenece el pago.

Request Body schema: application/json

Datos para la creación del pago.

payment

object (Payment_Form)

Responses

201

Pago creado correctamente.

400

Ha ocurrido algún error al validar la petición.

404

No se ha encontrado ninguna aplicación con el ID recibido.

post /application/{applicationId}/payment

https://api.payrest.com/application/{applicationId}/payment

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"payment": 
{"currency": "str",
"amount": 0,
"description": "string",
"clientId": "string",
"clientEmail": "string",
"urlOk": "string",
"urlKo": "string",
"askForClientDetails": false,
"type": 0,
"gatewayConfigs": 
["string"
]
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1/payment/1",
"rel": "self"
}
],
"id": 1,
"currency": "EUR",
"amount": "100",
"description": "Visita guiada",
"clientId": "ID_CLIENT_1",
"clientEmail": "client@example.com",
"status": "completed",
"urlOk": "https://example.org/ok",
"urlKo": "https://example.org/ko",
"createdAt": "2019-02-20T12:51:16+01:00",
"flags": 
["CANCELABLE",
"CHARGEABLE"
],
"transactionId": "V8dps1gIPVLs588PI",
"type": "Simple.",
"parentId": 0,
"children": 
[{ }
],
"completionDate": "2019-02-20T12:52:16+01:00",
"askForClientDetails": "false",
"gatewayConfigs": 
[{ }
]
}

Detalle

Información detallada sobre un pago concreto.

Authorizations:

ApiKeyOauth2

path Parameters

id required	integer \d+ Identificador único del pago.
applicationId required	integer \d+ Identificador único de la aplicación a la que pertenece el pago.

Responses

200

Solicitud correcta.

404

No se ha encontrado ninguna aplicación o ningún pago con el ID recibido.

get /application/{applicationId}/payment/{id}

https://api.payrest.com/application/{applicationId}/payment/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1/payment/1",
"rel": "self"
}
],
"id": 1,
"currency": "EUR",
"amount": "100",
"description": "Visita guiada",
"clientId": "ID_CLIENT_1",
"clientEmail": "client@example.com",
"status": "completed",
"urlOk": "https://example.org/ok",
"urlKo": "https://example.org/ko",
"createdAt": "2019-02-20T12:51:16+01:00",
"paymentLinks": 
[
{"paymentNumber": "9d04df59-9f77-447b-a764-83c658f65ded",
"details": { },
"gateway": "string",
"gatewayId": 0,
"gatewayName": "string",
"urlOk": "https://example.org/ok",
"urlKo": "https://example.org/ko"
}
],
"flags": 
["CANCELABLE",
"CHARGEABLE"
],
"transactionId": "V8dps1gIPVLs588PI",
"type": "Simple.",
"parentId": 0,
"children": 
[{ }
],
"completionDate": "2019-02-20T12:52:16+01:00",
"askForClientDetails": "false",
"gatewayConfigs": 
[
{"id": 1,
"gateway": "paypal_express_checkout",
"name": "FooInstance",
"weight": 0
}
],
"subscription": 
{"links": 
[
{"href": "https://example.org/application/1/subscription/1",
"rel": "self"
}
],
"id": 1,
"currency": "EUR",
"amount": "100",
"description": "Plan Premium",
"clientId": "CLIENT_ID_1",
"clientEmail": "client@example.com",
"status": "authorized",
"urlOk": "https://example.com/ok",
"urlKo": "https://example.com/ko",
"createdAt": "2020-02-10T12:13:26+01:00",
"transactionId": "V8dps1gIPVLs588PI",
"paymentCount": 12
}
}

Creación de enlace

Crea un nuevo enlace de pago que se puede enviar al usuario final para realizar el mismo.

Nota: Un enlace de pago siempre estará asociado a una pasarela de pago concreta, si se quiere enviar al usuario al cliente Secure de PayREST se deberá usar el enlace incluido en los detalles del propio pago (en enlace cuyo rel sea payment).

Authorizations:

ApiKeyOauth2

path Parameters

id required	integer \d+ Identificador único del pago.
applicationId required	integer \d+ Identificador único de la aplicación a la que pertenece el pago.

Request Body schema: application/json

Datos para la creación del enlace de pago.

paymentLink

object (Payment_Link_Form)

Responses

201

Enlace creado correctamente.

400

No es posible generar enlaces de pago para el pago recibido o los datos recibidos no son correctos.

404

No se ha encontrado ninguna aplicación o ningún pago con el ID recibido..

post /application/{applicationId}/payment/{id}

https://api.payrest.com/application/{applicationId}/payment/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"paymentLink": 
{"gatewayInstance": 1,
"urlOk": "string",
"urlKo": "string",
"clientId": "string",
"clientEmail": "string"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"paymentId": 1,
"transactionId": "6ACD6KBA3JJEAMQB5",
"paymentNumber": "add12310-fc94-4c6b-8595-54e4b083fbb1",
"urlOk": "https://example.org/success",
"urlKo": "https://example.org/fail",
"dataRequesterHtml": "string",
"links": 
[
{"href": "https://example.org/process/payment/PAYMENT_TOKEN",
"rel": "payment"
}
]
}

Cancelación

Cancela un pago y todos los enlaces asociados al mismo que todavía no se hayan finalizado, impidiendo que se llegue a completar el mismo.

Authorizations:

ApiKeyOauth2

path Parameters

id required	integer \d+ Identificador único del pago.
applicationId required	integer \d+ Identificador único de la aplicación a la que pertenece el pago.

Responses

204

Solicitud correcta.

400

No es posible aplicar el estado 'invalidated' al pago recibido.

404

No se ha encontrado el pago recibido.

delete /application/{applicationId}/payment/{id}

https://api.payrest.com/application/{applicationId}/payment/{id}

Webhooks

Los webhooks son peticiones que se realizan automáticamente a una URL cuando un pago cambia de estado.

En esta sección se detallarán los endpoints utilizados para gestionar los webhooks.

Nota: Los webhooks estarán siempre asociados a una aplicación concreta, por lo que todas las rutas incluirán el parámetro obligatorio applicationId.

Todas las peticiones procedentes de payrest como resultado de un webhook se envían firmadas con una cabecera Hash resultado de:

Crear un hash, con cifrado sha512, del body (en formato JSON) de la petición.
Concatenar este hash obtenido con el API_KEY de la aplicación.
Volver a crear otro hash, con cifrado sha512, del resultado del paso 2. Este será el que va en la cabecera.

$hash = hash('sha512', $apikeyValue.hash('sha512', $json_body));

Los receptores de dichas peticiones deberán generar, con su apikey y el body recibido en la petición, un hash que compararán con la cabecera recibida para asegurarse la procedencia de la petición.

Listado

Devuelve el listado de todos los webhooks configurados para una aplicación concreta.

Authorizations:

Oauth2

path Parameters

applicationId

required

integer \d+

Identificador único de la aplicación.

query Parameters

limit	integer >= 1 Default: 10 Número de elementos a mostrar por página.
offset	integer >= 0 Default: 0 Posición del primer elemento a mostrar.
sort	string Default: "id_asc" Campo y dirección de la ordenación de los resultados. El formato debe ser: field1_direction,field2_direction Donde: `fieldN`: Representa cualquiera de los campos de la entidad (devueltos en la respuesta). `direction`: Representa la dirección de ordenación, solo pudiendo ser esta `asc` o `desc`. Nota: En caso de no indicar `direction` para alguno de los campos se usará `asc`.

Responses

200

Solicitud correcta.

404

No se ha encontrado ninguna aplicación con el ID recibido.

get /application/{applicationId}/webhook

https://api.payrest.com/application/{applicationId}/webhook

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"url": "https://example.org/ipn",
"method": "POST",
"targets": 
["completed",
"failed"
],
"targetEntity": "payment"
}

Creación

Crea un nuevo webhook a partir de los datos recibidos.

Authorizations:

Oauth2

path Parameters

applicationId

required

integer \d+

Identificador único de la aplicación.

Request Body schema: application/json

Datos para la creación del webhook.

webhook

object (StatusEventType)

Responses

201

Webhook creado correctamente.

400

Ha ocurrido algún error al validar la petición.

404

No se ha encontrado ninguna aplicación con el ID recibido.

post /application/{applicationId}/webhook

https://api.payrest.com/application/{applicationId}/webhook

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"webhook": 
{"targetEntity": "payment",
"url": "https://example.org/ipn",
"method": "POST",
"targets": 
["completed",
"failed"
]
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"url": "https://example.org/ipn",
"method": "POST",
"targets": 
["completed",
"failed"
],
"targetEntity": "payment"
}

Borrado

Elimina un webhook, evitando que se ejecute en las próximas actualizaciones de pagos.

Authorizations:

Oauth2

path Parameters

id required	integer \d+ Identificador único del webhook.
applicationId required	integer \d+ Identificador único de la aplicación.

Responses

204

Solicitud correcta.

404

No se ha encontrado el webhook recibido.

delete /application/{applicationId}/webhook/{id}

https://api.payrest.com/application/{applicationId}/webhook/{id}

Suscripciones

Las suscripciones son las entidades que representan un acuerdo por el cual se realizará un pago en intervalos de tiempos regulares durante un periodo determinado.

En esta sección se detallarán los endpoints utilizados para gestionar una suscripción durante su vida completa, desde su creación a su posterior firma del acuerdo de suscripción o cancelación por parte del usuario final.

Nota: Las suscripciones estarán siempre asociadas a una aplicación concreta, por lo que todas las rutas incluirán el parámetro obligatorio applicationId.

Listado

Devuelve el listado completo de suscripciones para una aplicación.

Authorizations:

ApiKeyOauth2

path Parameters

applicationId

required

integer \d+

Identificador único de la aplicación a la que pertenece la suscripción.

query Parameters

limit	integer >= 1 Default: 10 Número de elementos a mostrar por página.
offset	integer >= 0 Default: 0 Posición del primer elemento a mostrar.
sort	string Default: "id_asc" Campo y dirección de la ordenación de los resultados. El formato debe ser: field1_direction,field2_direction Donde: `fieldN`: Representa cualquiera de los campos de la entidad (devueltos en la respuesta). `direction`: Representa la dirección de ordenación, solo pudiendo ser esta `asc` o `desc`. Nota: En caso de no indicar `direction` para alguno de los campos se usará `asc`.
status	string Estado de las suscripciones por el que filtrar el listado.

Responses

200

Solicitud correcta.

404

No se ha encontrado ninguna aplicación con el ID recibido.

get /application/{applicationId}/subscription

https://api.payrest.com/application/{applicationId}/subscription

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1/subscription/1",
"rel": "self"
}
],
"id": 1,
"currency": "EUR",
"amount": "100",
"description": "Plan Premium",
"clientId": "CLIENT_ID_1",
"clientEmail": "client@example.com",
"status": "authorized",
"urlOk": "https://example.com/ok",
"urlKo": "https://example.com/ko",
"createdAt": "2020-02-10T12:13:26+01:00",
"transactionId": "V8dps1gIPVLs588PI",
"paymentCount": 12
}

Creación

Crea una nueva suscripción a partir de la petición enviada por el cliente.

Authorizations:

ApiKeyOauth2

path Parameters

applicationId

required

integer \d+

Identificador único de la aplicación a la que pertenece la suscripción.

Request Body schema: application/json

Datos para la creación de la suscripción.

subscription

object (Subscription_Form)

Responses

201

Suscripción creada correctamente.

400

Ha ocurrido algún error al validar la petición.

404

No se ha encontrado ninguna aplicación con el ID recibido.

post /application/{applicationId}/subscription

https://api.payrest.com/application/{applicationId}/subscription

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"subscription": 
{"currency": "str",
"amount": 0,
"chargeInterval": null,
"paymentCount": 0,
"description": "string",
"clientId": "string",
"clientEmail": "string",
"urlOk": "string",
"urlKo": "string"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1/subscription/1",
"rel": "self"
}
],
"id": 1,
"currency": "EUR",
"amount": "100",
"description": "Plan Premium",
"clientId": "CLIENT_ID_1",
"clientEmail": "client@example.com",
"status": "authorized",
"urlOk": "https://example.com/ok",
"urlKo": "https://example.com/ko",
"createdAt": "2020-02-10T12:13:26+01:00",
"transactionId": "V8dps1gIPVLs588PI",
"paymentCount": 12
}

Detalle

Información detallada sobre una suscripción concreta.

Authorizations:

ApiKeyOauth2

path Parameters

id required	integer \d+ Identificador único de la suscripción.
applicationId required	integer \d+ Identificador único de la aplicación a la que pertenece la suscripción.

Responses

200

Solicitud correcta.

404

No se ha encontrado ninguna aplicación o suscripción con el ID recibido.

get /application/{applicationId}/subscription/{id}

https://api.payrest.com/application/{applicationId}/subscription/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"links": 
[
{"href": "https://example.org/application/1/subscription/1",
"rel": "self"
}
],
"id": 1,
"currency": "EUR",
"amount": "100",
"description": "Plan Premium",
"clientId": "CLIENT_ID_1",
"clientEmail": "client@example.com",
"status": "authorized",
"urlOk": "https://example.com/ok",
"urlKo": "https://example.com/ko",
"createdAt": "2020-02-10T12:13:26+01:00",
"transactionId": "V8dps1gIPVLs588PI",
"paymentCount": 12
}

Creación de acuerdo

Crea un nuevo acuerdo de suscripción que opcionalmente puede devolver un HTML que se debe enviar al usuario final para confirmar el mismo.

Authorizations:

ApiKeyOauth2

path Parameters

id required	integer \d+ Identificador único de la suscripción.
applicationId required	integer \d+ Identificador único de la aplicación a la que pertenece la suscripción.

Request Body schema: application/json

Datos para la creación del acuerdo de suscripción.

subscriptionAgreement

object (Subscription_Agreement_Form)

Responses

201

Enlace creado correctamente.

400

No es posible generar acuerdos de suscripción para la suscripción recibida o los datos recibidos no son correctos.

404

No se ha encontrado ninguna aplicación o ninguna suscripción con el ID recibido.

post /application/{applicationId}/subscription/{id}

https://api.payrest.com/application/{applicationId}/subscription/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"subscriptionAgreement": 
{"gateway": 1,
"urlOk": "string",
"urlKo": "string"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"subscriptionId": 1,
"transactionId": "6ACD6KBA3JJEAMQB5",
"paymentNumber": "add12310-fc94-4c6b-8595-54e4b083fbb1",
"urlOk": "https://example.com/success",
"urlKo": "https://example.com/fail",
"dataRequesterHtml": "string",
"links": 
[
{"href": "https://example.org/process/subscription/SUBSCRIPTION_TOKEN",
"rel": "subscription"
}
]
}

Cancelación

Cancela una suscripción y todos los acuerdos de suscripción asociados a la misma que todavía no se hayan finalizado. Esto implica que no se generarán más pagos para esta suscripción y que los pagos que ya estén encolados para ejecución no se lleguen a crear (esto no aplica si el último pago está pendiente de confirmación pero ya se ha hecho la petición de autorización a la pasarela).

Authorizations:

ApiKeyOauth2

path Parameters

id required	integer \d+ Identificador único de la suscripción.
applicationId required	integer \d+ Identificador único de la aplicación a la que pertenece la suscripción.

Responses

204

Solicitud correcta.

400

No es posible aplicar el estado 'invalidated' a la suscripción recibida.

404

No se ha encontrado la suscripción recibida.

delete /application/{applicationId}/subscription/{id}

https://api.payrest.com/application/{applicationId}/subscription/{id}

Usuarios

Los usuarios representan cada uno de los usuarios finales que podrán autenticarse contra el servidor OAuth2 de Ipglobal para acceder a los diferentes recursos de la API.

En esta sección se detallarán los endpoints utilizados para gestionar un usuario y los permisos del mismo.

Nota: Los usuario siempre estarán asociados a un cliente concreto, por lo que todas las rutas incluirán el parámetro obligatorio clientId.

Listado

Listado de todos los usuarios pertenecientes a un cliente.

Authorizations:

Oauth2

path Parameters

clientId

required

string

Identificador único del cliente.

query Parameters

limit	integer >= 1 Default: 10 Número de elementos a mostrar por página.
offset	integer >= 0 Default: 0 Posición del primer elemento a mostrar.
sort	string Default: "id_asc" Campo y dirección de la ordenación de los resultados. El formato debe ser: field1_direction,field2_direction Donde: `fieldN`: Representa cualquiera de los campos de la entidad (devueltos en la respuesta). `direction`: Representa la dirección de ordenación, solo pudiendo ser esta `asc` o `desc`. Nota: En caso de no indicar `direction` para alguno de los campos se usará `asc`.

Responses

200

Petición correcta.

404

No se ha encontrado ningún cliente con el ID recibido.

get /client/{clientId}/user

https://api.payrest.com/client/{clientId}/user

Response samples

Content type

application/json

Copy

Expand all Collapse all


[
{"id": 1,
"username": "example1",
"email": "user1@example.com",
"roles": 
["USER"
],
"uuid": "cb461867-b06a-4632-b70e-ee46247f9634",
"links": 
[
{"href": "https://example.org/client/1/user/1",
"rel": "self"
}
]
}
]

Creación

Permite crear un usuario, devolviendo a su vez los datos completos del mismo si la petición es correcta.

Authorizations:

Oauth2

path Parameters

clientId

required

string

Identificador único del cliente.

Request Body schema: application/json

Datos para la creación del usuario.

user	object (UserType)

Responses

201

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

404

No se ha encontrado ningún cliente con el ID recibido.

post /client/{clientId}/user

https://api.payrest.com/client/{clientId}/user

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"user": 
{"username": "example_user",
"email": "user@example.org",
"roles": 
["ADMIN"
],
"firstName": "John",
"lastName": "Doe"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"username": "example1",
"email": "user1@example.com",
"roles": 
["USER"
],
"uuid": "cb461867-b06a-4632-b70e-ee46247f9634",
"links": 
[
{"href": "https://example.org/client/1/user/1",
"rel": "self"
}
]
}

Detalle

Información detallada sobre un usuario concreto.

Authorizations:

Oauth2

path Parameters

id required	integer \d+ Identificador único del usuario.
clientId required	string Identificador único del cliente.

Responses

200

Solicitud correcta.

404

No se encontrado ningún cliente o usuario con el ID recibido.

get /client/{clientId}/user/{id}

https://api.payrest.com/client/{clientId}/user/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"username": "example1",
"email": "user1@example.com",
"roles": 
["USER"
],
"uuid": "cb461867-b06a-4632-b70e-ee46247f9634",
"links": 
[
{"href": "https://example.org/client/1/user/1",
"rel": "self"
}
]
}

Edición

Edición del usuario indicado. Los campos que no se encuentren en la petición se establecerán a null.

Authorizations:

Oauth2

path Parameters

id required	integer \d+ Identificador único del usuario.
clientId required	string Identificador único del cliente.

Request Body schema: application/json

Datos para la edición del usuario.

user	object (UserType)

Responses

200

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

404

No se ha encontrado ningún cliente o usuario con el ID recibido.

put /client/{clientId}/user/{id}

https://api.payrest.com/client/{clientId}/user/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"user": 
{"username": "example_user",
"email": "user@example.org",
"roles": 
["ADMIN"
],
"firstName": "John",
"lastName": "Doe"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"username": "example1",
"email": "user1@example.com",
"roles": 
["USER"
],
"uuid": "cb461867-b06a-4632-b70e-ee46247f9634",
"links": 
[
{"href": "https://example.org/client/1/user/1",
"rel": "self"
}
]
}

Edición

Edición del usuario indicado. Solo se modificarán los campos que aparezcan explícitamente en la petición.

Authorizations:

Oauth2

path Parameters

id required	integer \d+ Identificador único del usuario.
clientId required	string Identificador único del cliente.

Request Body schema: application/json

Datos para la edición del usuario.

user	object (UserType)

Responses

200

Solucitud correcta.

400

Ha ocurrido algún error al validar la petición.

404

No se ha encontrado ningún cliente o usuario con el ID recibido.

patch /client/{clientId}/user/{id}

https://api.payrest.com/client/{clientId}/user/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"user": 
{"username": "example_user",
"email": "user@example.org",
"roles": 
["ADMIN"
],
"firstName": "John",
"lastName": "Doe"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": 1,
"username": "example1",
"email": "user1@example.com",
"roles": 
["USER"
],
"uuid": "cb461867-b06a-4632-b70e-ee46247f9634",
"links": 
[
{"href": "https://example.org/client/1/user/1",
"rel": "self"
}
]
}

Borrado

Borra el usuario recibido en la petición.

Authorizations:

Oauth2

path Parameters

id required	integer \d+ Identificador único del usuario.
clientId required	string Identificador único del cliente.

Responses

204

Usuario borrado correctamente.

404

No se ha encontrado ningún cliente o usuario con el ID recibido.

delete /client/{clientId}/user/{id}

https://api.payrest.com/client/{clientId}/user/{id}

Servicios de pago

Los servicios de pago son los diferentes servicios con los que se integra PayREST (Redsýs, PayPal, etc).

En esta sección se detallarán los endpoints utilizados para obtener un listado de los diferentes servicios disponibles, así como obtener información concreta sobre uno de ellos (como por ejemplo las diferentes opciones de configuración que admite).

Listado

Listado de todos los servicios de pago disponibles para configurar, así como del número de instancias de cada una que el cliente actual tiene configuradas.

Authorizations:

ApiKeyOauth2

Responses

200

Petición correcta.

get /gateway

https://api.payrest.com/gateway

Response samples

Content type

application/json

Copy

Expand all Collapse all


[
{"enabled": true,
"name": "PayPal ExpressCheckout",
"options": 
{"username": 
{"type": "string",
"required": true
},
"password": 
{"type": "string",
"required": true
},
"signature": 
{"type": "string",
"required": true
},
"sandbox": 
{"type": "boolean",
"required": false
}
},
"instances": 2,
"links": 
[
{"href": "https://example.org/gateway/offline",
"rel": "self"
}
],
"id": "paypal_express_checkout"
}
]

Detalle

Listado detallado de los datos de un servicio de pago, así como las posibles opciones que se pueden configurar en el mismo y las instancias que tiene configuradas el cliente actual.

Authorizations:

ApiKeyOauth2

path Parameters

required

string

Identificador único del servicio de pago.

Responses

200

Solicitud correcta.

404

No se ha encontrado ningún servicio de pago con el ID solicitado.

get /gateway/{id}

https://api.payrest.com/gateway/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"enabled": true,
"name": "PayPal ExpressCheckout",
"options": 
{"username": 
{"type": "string",
"required": true
},
"password": 
{"type": "string",
"required": true
},
"signature": 
{"type": "string",
"required": true
},
"sandbox": 
{"type": "boolean",
"required": false
}
},
"instances": 2,
"id": "paypal_express_checkout",
"configuredInstances": [ ]
}

Estadísticas de aplicación

PayREST pone a disposición de los desarrolladores diferentes estadísticas pre-calculadas tanto generales para un cliente concreto como asociadas a una aplicación concreta.

En esta sección se detallarán los endpoints utilizados para obtener estos datos, así como los datos exactos que se devuelven.

Resumen de operaciones totales

Muestra un resumen de operaciones e importes totales por aplicación, además de la suma de todas las operaciones del cliente actual.

Authorizations:

Oauth2

Responses

200

Petición correcta.

get /stats/operations/summary

https://api.payrest.com/stats/operations/summary

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"totalCount": 100,
"totalAmount": 100000000,
"details": 
[
{"id": 1,
"name": "Example App",
"count": 100,
"amount": 100000000
}
]
}

Resumen de operaciones por día

Muestra un resumen de operaciones e importes totales por día y por aplicación, así como el total de operaciones e importes en el período filtrado.

Authorizations:

Oauth2

query Parameters

from	string Fecha de inicio del rango a obtener en formato YYYY-mm-dd. Por defecto, será una semana menos de la fecha actual.
to	string Fecha de fin del rango a obtener en formato YYYY-mm-dd. Por defecto, será el día actual.

Responses

200

Petición correcta.

get /stats/operations/daily

https://api.payrest.com/stats/operations/daily

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"from": "2019-09-28",
"to": "2019-10-05",
"data": 
[
{"date": "2019-09-28",
"completed": 10,
"failed": 5,
"invalidated": 7
}
]
}

Resumen de operaciones por gateway

Muestra un resumen de operaciones totales por gateway para una aplicación concreta.

Authorizations:

Oauth2

path Parameters

required

integer \d+

Identificador único de la aplicación.

Responses

200

Petición correcta.

get /application/{id}/stats/summary

https://api.payrest.com/application/{id}/stats/summary

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"totalCount": 100,
"totalAmount": 100000000,
"details": 
[
{"id": 1,
"name": "PayPalInstance",
"count": 100,
"amount": 100000000
}
]
}

Resumen de operaciones por día para una aplicación concreta

Muestra un resumen de operaciones por estado y día para una aplicación concreta.

Authorizations:

Oauth2

path Parameters

required

integer \d+

Identificador único de la aplicación.

query Parameters

from	string Fecha de inicio del rango a obtener en formato YYYY-mm-dd. Por defecto, será una semana menos de la fecha actual.
to	string Fecha de fin del rango a obtener en formato YYYY-mm-dd. Por defecto, será el día actual.

Responses

200

Petición correcta.

get /application/{id}/stats/daily

https://api.payrest.com/application/{id}/stats/daily

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"from": "2019-09-28",
"to": "2019-10-05",
"data": 
[
{"date": "2019-09-28",
"new": 2,
"pending": 5,
"suspended": 3,
"completed": 10,
"failed": 5,
"expired": 32,
"canceled": 8,
"refunded": 3,
"payedout": 16,
"authorized": 15,
"unknown": 5,
"invalidated": 7,
"accepting_payments": 4
}
]
}

Detalle de operaciones del cliente

Muestra un listado de operaciones por cliente. Se listarán las operaciones de todas las aplicaciones y gateways. Admite filtado por rango de fechas en la que se confirmaron los pagos.

Authorizations:

Oauth2

query Parameters

from	string Fecha de inicio del rango a obtener en formato YYYY-mm-dd. Por defecto, será una semana menos de la fecha actual.
to	string Fecha de fin del rango a obtener en formato YYYY-mm-dd. Por defecto, será el día actual.

Responses

200

Petición correcta.

get /stats/operations/detail

https://api.payrest.com/stats/operations/detail

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"from": "2019-09-28",
"to": "2019-10-05",
"data": 
[
{"applicationName": "Example App",
"gatewayName": "FooInstance",
"id": 1,
"transactionId": "ABC1234567890DEFG",
"status": "completed",
"amount": 10000,
"currency": "EUR",
"completionDate": "2019-09-28"
}
]
}