# Manual API Pagos

# Manual API Pagos

Para permitir que cualquier usuario pueda utilizar Premiumpay como procesador de pagos independiente se necesita un API que permita ejecutarlo desde otros sistemas. Este documento sirve de base para la creación de ese API.

Todas las llamadas usarán JSON en el cuerpo de la llamada a no ser que se especifique otra cosa.

## Autenticación

Todo cliente de Premiumpay podrá utilizar el API si está autorizado para ello. Se utilizará su cuenta de **"tipster"** (login_business) como fuente de sus credenciales y límites (si los hubiese). El usuario podrá utilizar el gestor de Premiumpay para ver y gestionar sus pagos hechos por API.

Para poder utilizar el API se incluirá en la cabecera:

```
Authorization: Bearer api_key_producto
```

Los pagos irán relacionados con una pasarela y un producto concreto del usuario para que pueda verlos en el gestor. Si el api_key no es válido se devolverá un error **403**. Si el api_key es correcto pero no se tiene permiso para usar el API se devolverá **401** si no se reconoce el API key.

## Operativa cliente

El cliente podrá crear un producto dentro de cualquier pasarela especificando que es del tipo API. Esto le creará una apikey que será la que tenga que utilizar para las llamadas al API. El APIKEY se le mostrará al usuario en la ficha de su producto. Los valores que ingrese de nombre, descripción y precio (y precio en divisas) serán tomados como valores por defecto para las llamadas al API que no contengan estos datos.

## Métodos de pago disponibles

```
POST /available_methods
```

Devuelve la lista de los medios de pago que se pueden utilizar para una IP y cantidad determinada.

### Parámetros de entrada

* **clientIP** — dirección IP del cliente (determina el país)
* **amount** — cantidad con decimales a pagar (ej. 10.5) en euros

### Salida

* **status** — ok | ko
* **paymentMethods** — array de objetos de formas de pago:
  * **id** — identificador del medio de pago a incluir en la lista de paymentMethods en makepayments
  * **img** — URL de la imagen que representa el medio de pago
  * **autoskip_selection** — true|false indica si se puede ir directamente al pago con este medio sin pasar por el selector de medios de pago de Premiumpay
  * **required_fields** — lista de cadenas separadas por coma con el nombre de los campos requeridos para empezar el pago
* **error** — mensaje de error

## Solicitar un cobro

```
POST /api/makepayment
```

### Parámetros de entrada

* **clientOrderId** — ID del pedido de cliente (propio del sistema del cliente y sin restricción)
* **amount** — cantidad (dos decimales)
* **currency** — moneda en ISO
* **productDescription** — descripción del producto
* **productName** — nombre del producto
* **clientIP** — IP del cliente final que hace la petición
* **clientEmail** — email del cliente final que hace la petición
* **okurl** — URL a la que redirigir en caso de que el pago sea satisfactorio
* **kourl** — URL a la que redirigir en caso de que el pago haya fallado
* **cancelurl** — URL a la que redirigir en caso de que el usuario cancele (opcional)
* **callbackurl** — URL a la que informar del pago (ver sección callback)
* **paymentMethods** — array de medios de pagos que queremos usar. Si ese medio de pago está deshabilitado por configuración se permitirá
* **tokenizer** — true|false si se quiere tokenizar el pago para poder hacer pagos recurrentes
* **token** — token del medio de pago para pagos recurrentes
* **expiry** — número de minutos durante los que será válido el pago (si no aparece, el pago no caduca)
* **headers** — true|false indica si queremos que aparezcan las cabeceras y pies de página de Premiumpay
* **required_fields** — objeto con los valores de los campos requeridos en la forma `{"campo": "valor"}`

### Lista actual de medios de pago

* Stripe
* Tarjeta
* Bizum
* AstroPay
* Payretailers (varios según país)
* PayU
* PayPal
* Coinbase

### Salida

* **status** — estado de la petición (ok | ko)
* **paymentId** — ID Premiumpay del prepago
* **redirecturl** — La URL de redirección
* **message** — Mensaje de la operación

## Callback

Los callback indicados en makepayment serán llamados antes de redirigir a alguna de las URL resultado (okurl, kourl o cancelurl) con el resultado del pago del cliente. Las llamadas se harán por POST y con estos parámetros:

* **clientOrderId**
* **paymentId**
* **amount**
* **currency**
* **status**
* **message**
* **card**
* **paymentMethod**
* **token** — el token en caso de pago recurrente (NOT_VALID si no se ha podido tokenizar)

Para aumentar la seguridad se entregará en la cabecera el mismo token que el usado por el cliente:

```
Authorization: Bearer api_key_producto
```

En esta primera versión no se esperará un resultado satisfactorio de la llamada, cualquier resultado (salvo el error de conexión) permitirá seguir con el flujo normal del pago.

## Curl de ejemplo

### Version

```bash
curl --header --location 'https://dev.premiumpay.pro/api/v1/version' \
--header 'Accept: application/json'
```

### Status

```bash
curl --location 'https://dev.premiumpay.pro/api/v1/status' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer pp_6500dcf9b3278'
```

### Makepayment

```bash
curl --location 'https://dev.premiumpay.pro/api/v1/makepayment' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer pp_6500dcf9b3278' \
--data-raw '{
  "amount": 10.01,
  "currency": "EUR",
  "productDescription": "Product API description",
  "productName": "Product API name",
  "clientOrderId": "12345ORD6789",
  "clientIP": "154.36.22.12",
  "clientEmail": "email@demo.com",
  "okurl": "https://demo.com/success",
  "kourl": "https://demo.com/failure",
  "callbackurl": "https://demo.com/callback",
  "cancelurl": "https://demo.com/cancel",
  "paymentMethods": ["Stripe2", "Bizum"]
}'
```

### Makepayment para tokenizar

```bash
curl --location 'https://dev.premiumpay.pro/api/v1/makepayment' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer pp_6500dcf9b3278' \
--data-raw '{
  "amount": 10.01,
  "currency": "EUR",
  "productDescription": "Product API description",
  "productName": "Product API name",
  "clientOrderId": "12345ORD6789",
  "clientIP": "154.36.22.12",
  "clientEmail": "email@demo.com",
  "okurl": "https://demo.com/success",
  "kourl": "https://demo.com/failure",
  "callbackurl": "https://demo.com/callback",
  "cancelurl": "https://demo.com/cancel",
  "paymentMethods": ["Stripe2"],
  "tokenizer": true
}'
```

### Makepayment para hacer pago recurrente

```bash
curl --location 'https://dev.premiumpay.pro/api/v1/makepayment' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer pp_6500dcf9b3278' \
--data-raw '{
  "amount": 10.01,
  "currency": "EUR",
  "productDescription": "Product API description",
  "productName": "Product API name",
  "clientOrderId": "12345ORD6789",
  "clientIP": "154.36.22.12",
  "clientEmail": "email@demo.com",
  "callbackurl": "https://demo.com/callback",
  "token": "e608f10edfbfd798574352324a260c78"
}'
```