-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapiculqihenry.yaml
4766 lines (4695 loc) · 175 KB
/
apiculqihenry.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.0
info:
title: CULQI API
version: '1.0'
description: |
# Introducción
La API de [Culqi](http://culqi.com/) está construido bajo los estándares de **REST**. Es decir, nuestra API posee URLs orientada a recursos, y hace uso de los [códigos de respuesta HTTP](https://httpstatuses.com/) para indicar los posibles errores en el API. Es importante indicar que se encuentra implementada una autenticación HTTP (<em>Bearer Token</em>), solicitada en cada petición. A<demás, soportamos las solicitudes HTTP de origen cruzdo (CORS), permitiendo que tu sitio y Culqi puedan interactuar de manera segura mediante nuestra API desde una aplicación cliente (aunque NUNCA deberías exponer tu Llave Secreta en el código de la aplicación web cliente). Por otro lado, un objeto JSON es retornado en cada una las peticiones hacia el API, incluyendo los errores. Adicionalmente nuestras bibliotecas convierten las respuestas en objetos específicos para cada lenguaje soportado.
Finalmente, para que puedas comenzar a experimentar con nuestra API, todas las cuentas registradas en Culqi poseen llaves para el entorno de pruebas (Regístrate y obtén tus llaves) y el entorno de producción. Usando las llaves de prueba las transacciones nunca pasan por las redes bancarias y no tienen ningún costo. (¡Recuerda usar tarjetas de prueba, no tarjetas reales al probar!).
<div class="cntrecursos">
<a href="#tag/Tokens">
<div class="cnttoken">
<div class="cnttokenup">
<div class="contentimgtokenletra">
<div class="cntimgtoken"><img src="assets/images/boxes/tokens.png" width="40"></div>
<div class="cnttextotoken"> <strong>Tokens</strong>
<br><span> /tokens</span> </div>
</div>
<div class="cntimgletrintokenurl"><img src="assets/images/flechon.jpg"></div>
</div>
<div class="cnttokenlower"> Captura de manera segura datos sensibles de tarjetas de crédito y débito directamente desde el navegador de tu cliente sin que toquen tus servidores.</div>
</div>
</a>
<a href="#tag/Cargos">
<div class="cnttoken" style="margin-right:0px;">
<div class="cnttokenup">
<div class="contentimgtokenletra">
<div class="cntimgtoken"><img src="assets/images/boxes/charges.png" width="40"></div>
<div class="cnttextotoken"> <strong>Cargos</strong>
<br><span> /charges</span> </div>
</div>
<div class="cntimgletrintokenurl"><img src="assets/images/flechon.jpg"></div>
</div>
<div class="cnttokenlower"> Realiza un cargo o cobro a las tarjetas de crédito o débito de tus clientes usando un token de cargo único o una tarjeta que haya sido guardada previamente. </div>
</div>
</a>
<a href="#tag/Planes">
<div class="cnttoken">
<div class="cnttokenup">
<div class="contentimgtokenletra">
<div class="cntimgtoken"><img src="assets/images/boxes/plans.png" width="40"></div>
<div class="cnttextotoken"> <strong>Planes</strong>
<br><span> /plans</span> </div>
</div>
<div class="cntimgletrintokenurl"><img src="assets/images/flechon.jpg"></div>
</div>
<div class="cnttokenlower"> Define un plan que contenga información acerca del tipo de cargo, frecuencia, intervalo y monto que quieres cobrarle a un cliente de manera recurrente. </div>
</div>
</a>
<a href="#tag/Suscripciones">
<div class="cnttoken" style="margin-right:0px;">
<div class="cnttokenup">
<div class="contentimgtokenletra">
<div class="cntimgtoken"><img src="assets/images/boxes/subscriptions.png" width="40"></div>
<div class="cnttextotoken"> <strong>Suscripciones</strong>
<br><span> /subscriptions</span> </div>
</div>
<div class="cntimgletrintokenurl"><img src="assets/images/flechon.jpg"></div>
</div>
<div class="cnttokenlower"> Realiza cargos recurrentes a tus clientes asociando una tarjeta de crédito o débito guardada con un plan de suscripción creado previamente. </div>
</div>
</a>
<a href="#tag/Clientes">
<div class="cnttoken">
<div class="cnttokenup">
<div class="contentimgtokenletra">
<div class="cntimgtoken"><img src="assets/images/boxes/customers.png" width="40"></div>
<div class="cnttextotoken"> <strong>Clientes</strong>
<br><span> /customers</span> </div>
</div>
<div class="cntimgletrintokenurl"><img src="assets/images/flechon.jpg"></div>
</div>
<div class="cnttokenlower"> Crear un cliente te permitirá asociar un usuario a una o varias tarjetas de crédito o débito para realizarles cargos recurrentes o pagos en un solo click. </div>
</div>
</a>
<a href="#tag/Tarjetas">
<div class="cnttoken" style="margin-right:0px;">
<div class="cnttokenup">
<div class="contentimgtokenletra">
<div class="cntimgtoken"><img src="assets/images/boxes/cards.png" width="40"></div>
<div class="cnttextotoken"> <strong>Tarjetas</strong>
<br><span> /cards</span> </div>
</div>
<div class="cntimgletrintokenurl"><img src="assets/images/flechon.jpg"></div>
</div>
<div class="cnttokenlower"> Guarda información de las tarjetas de tus clientes frecuentes para realizarles cargos sin que vuelvan a colocar toda la información de sus tarjetas de crédito o débito. </div>
</div>
</a>
</div>
# Autenticación
Para poder acceder y utilizar la API de Culqi necesitas previamente obtener tus [Llaves de Autenticación](https://docs.culqi.com/#/cuenta/cuenta#llaves) e incluirlas en cada petición que hagas al API. Podrás encontrar tus llaves en el Panel de [Integración](http://integ-panel.culqi.com/) y [Producción](http://panel.culqi.com/) de Culqi.
<div class="box warning"><div class="content">Ten en cuenta que es información muy sensible y no puedes compartirlas con nadie.</div></div>
Para usar el API de Culqi utiliza autenticación Bearer como se muestra a continuación :
**Ejemplo de Autenticación:**
```
-H "Authorization: Bearer sk_test_UTCQSGcXW8bCyU59"
```
Todas las peticiones al API deben ser hechas bajo el protocolo de transferencia [HTTPS.](https://es.wikipedia.org/wiki/Hypertext_Transfer_Protocol_Secure) Las llamadas hechas bajo el protocolo HTTP plano fallarán en el [entorno de producción](https://docs.culqi.com/#/cuenta/cuenta) al igual que las peticiones sin autenticación.
# Errores
Por medio de nuestra API, podrás ser notificado con toda la información en caso presentes un error al momento de hacer una petición a cualquier operación del API. La API de Culqi utiliza el estándar de Códigos de Estado HTTP (HTTP Status Codes) en todas sus respuestas para indicar si las solicitudes se pudieron procesar con éxito o fallaron.
## Objeto Error
## Códigos HTTP
Culqi usa los siguientes códigos de estado HTTP en sus respuestas:
| Código | HTTP Status | Descripción |
|--------|-------------|-------------------------------------|
| 200 | OK | Todo ha salido a la perfección. |
| 201 | Created | Un nuevo recurso ha sido creado. (POST). |
| 204 | No Content | El recurso fue exitosamente eliminado. (DELETE) |
| 400 | Bad Request | La petición al servidor no ha podido ser procesada debido a una sintáxis incorrecta. |
| 401 | Unauthorized | La llave API utilizada es inválida. |
| 402 | Payment Required | El pago no pudo ser procesado. |
| 404 | Not Found | El recurso solicitado en la llamada no existe. |
| 422 | Unprocessable Entity | La sintaxis de la llamada es válida pero la información dentro de los parámetros es inválida. |
| 500 y 503 | Server Errors | Error en los servidores Culqi y la petición no pudo ser procesada. |
## Tipos de Errores
Culqi devuelve los siguientes tipos de errores relacionados con los códigos de estado HTTP en sus respuestas:
| Type| HTTP Status Code - Descripción |
|--------|-------------|
| invalid_request_error| HTTP 400 - La petición tiene una sintaxis inválida.|
| authentication_error| HTTP 401 - La petición no pudo ser procesada debido a problemas con las llaves.|
| parameter_error| HTTP 422 - Algún parámetro de cualquier petición es inválido.|
| card_error| HTTP 402 - No se pudo realizar el cargo a una tarjeta.|
| limit_api_error| HTTP 429 - Estás haciendo muchas peticiones rápidamente al API o superaste tu límite designado.|
| resource_error| HTTP 404 - El recurso no puede ser encontrado, es inválido o tiene un estado diferente al permitido.|
| api_error| HTTP 500 y 503 - Engloba cualquier otro tipo de error (Ejemplo: problema temporal con los servidores de Culqi) y debería de ocurrir muy pocas veces.|
## Codigos de Denegación de Bancos
Culqi devuelve los siguientes tipos de denegaciones devueltas por los bancos:
| Decline Code | Explicación |
|--------|-------------|
| expired_card | Tarjeta vencida. La tarjeta está vencida o la fecha de vencimiento ingresada es incorrecta.|
| stolen_card| Tarjeta robada. La tarjeta fue bloqueada y reportada al banco emisor como una tarjeta robada|
| lost_card| Tarjeta perdida. La tarjeta fue bloqueada y reportada al banco emisor como una tarjeta perdida.|
| insufficient_funds| Fondos insuficientes. La tarjeta no tiene fondos suficientes para realizar la compra.|
| contact_issuer| Contactar emisor. La operación fue denegada por el banco emisor de la tarjeta y el cliente necesita contactarse con la entidad para conocer el motivo.|
| invalid_cvv| CVV inválido. El código de seguridad (CVV2, CVC2, CID) de la tarjeta es inválido.|
| too_many_attempts_cvv| Exceso CVV. El cliente ha intentado demasiadas veces ingresar el código de seguridad (CVV2, CVC2, CID) de la tarjeta.|
| issuer_not_available| Emisor no disponible. El banco que emitió la tarjeta no responde. El cliente debe realizar el pago nuevamente.|
| issuer_decline_operation| Operación denegada. La operación fue denegada por el banco emisor de la tarjeta por una razón desconocida.|
|invalid_card| Tarjeta inválida. La tarjeta utilizada tiene restricciones para este tipo de compras. El cliente necesita contactarse con el banco emisor para conocer el motivo de la denegación.|
|processing_error| Error de procesamiento. Ocurrió un error mientras procesabamos la compra. Contáctate con culqi.com/soporte para que te demos una solución.|
|fraudulent| Operación fraudulenta. El banco emisor de la tarjeta sospecha que se trata de una compra fraudulenta.|
|culqi_card| Tarjeta Culqi. Estás utilizando una tarjeta de pruebas de Culqi para realizar una compra real.|
|soft_block| Tarjeta con bloqueo temporal por reintentos. El cliente debe intentar nuevamente con otra tarjeta.|
## Casos de Errores
A continuación te presentamos una serie de ejemplos de errores comunes a la hora de integrar la API de Culqi.
# Metadata
La metadata es una manera útil de guardar información adicional de manera estructurada en un objeto. Todos los recursos de Culqi, incluyendo [Tokens](#tag/Tokens), [Cargos](#tag/Cargos), [Planes](#tag/Planes), [Suscripciones](#tag/Suscripciones), [Devoluciones](#tag/Devoluciones), [Tarjetas](#tag/Tarjetas), [Clientes](#tag/Tarjetas) tienen un parámetro metadata que puede ser utilizado para reflejar información clave de tu negocio que quieras relacionar con las operaciones.
Por ejemplo, en el parámetro *metadata* del recurso [Clientes](#tag/Clientes) podrías guardar el nombre completo de tu cliente, su número de documento de identidad y su fecha de nacimiento. La *metadata* no es utilizada por Culqi para analizar, realizar o rechazar un cargo.
<div class="box info"><div class="content">El atributo metadata no puede tener más de 20 objetos clave-valor. Adicionalmente, la clave no podrá exceder de 30 caracteres y el valor de 200 caracteres.</div></div>
**Ejemplos de Metadata** </br>
Por ejemplo, en la petición para [crear un cargo](#operation/crear-cargo) al API, podrías enviar a través del objeto metadata los valores definidos anteriormente:
```json
{
"amount":200,
"currency_code":"PEN",
"source_id":"tkn_live_189fqQ2eZvKYlo2",
"description":"Apple Watch Series 20",
"installments":6,
"capture":true,
"metadata": {
"order_id":"204055",
"user_id":"4625",
"user_details":"46734527"
}
}
```
Aquí te presentamos algunas sugerencias para los valores de *metadata:*
<SchemaDefinition schemaRef="#/components/schemas/Metadata" hideSamples={false}/>
# Paginación
Todos los recursos principales de Culqi soportan operaciones de listado, entre ellos Tokens, Cargos, Transferencias, Tarjetas, Clientes, Suscripciones, Devoluciones y Planes. Adicionalmente, todos los métodos de listado del API comparten una estructura similar tomando en cuenta estos tres parámetros: limit, after y before.
Culqi utiliza una paginación en tiempo real basada en cursor a través de los parámetros after y before. Un cursor se refiere a un string de caracteres random que marca un ítem específico en una lista de datos. A menos que el ítem sea borrado, el cursor siempre estará punteando la misma parte de la lista, pero será invalidado si el ítem es removido.
En Culqi, los parámetros after y before toman el valor ID y retornan los objetos en un orden cronológico reverso. El parámetro before devuelve los objetos creados antes del objeto en cuestión. El parámetro after devuelve los objetos creados después del objeto en cuestión. Si ambos parámetros son provistos sólo before es utilizado.
# ID de Rastreo
Cada petición al API está asociada a un identificador de rastreo. Puedes encontrar este valor en los headers de respuesta, bajo el nombre de x-culqi-tracking-id, también lo puedes encontrar en el Panel de Culqi y en el detalle de cada petición.
:::attention
Si necesitas ayuda con alguna petición en específico, brindando este ID de rastreo hará más fácil la ubicación y posterior solución del problema o incidencia.
:::
<div class="box info"><div class="content">Si necesitas ayuda con alguna petición en específico, brindando este ID de rastreo hará más fácil la ubicación y posterior solución del problema o incidencia.</div></div>
**Ejemplo de Headers de Respuesta:**
```json Headers
"date": "1476132639",
"x-culqi-environment": "live",
"x-culqi-tracking-id": "9283",
"x-culqi-version": "17.01.89",
"content-type": "application/json"
```
Atributos:
<SchemaDefinition schemaRef="#/components/schemas/Rastreo" hideSamples={false} />
| Parámetro | Tipo | Descripcion |
| --- | --- | --- |
| <span class="property-name">date</span> <br/> <div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div> | string | Fecha en la que se creó la petición en [UNIX Timestamp.](http://www.unixtimestamp.com/)<br/>Ejemplo: "1476132639" |
| <span class="property-name">x-culqi-environment</span> <div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div> | string | Fecha en la que se creó la petición en [UNIX Timestamp.](http://www.unixtimestamp.com/)<br/>Ejemplo: "live"<br/>Posibles valores: live, test |
| <span class="property-name">x-culqi-tracking-id</span> <div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div> | string | Código de identificación de la petición.<br/>Ejemplo: "9283" |
| <span class="property-name">x-culqi-version</span> <div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div> | string | Número de versión del API.<br/>Ejemplo: "17.01.89" |
| <span class="content-type">x-culqi-version</span> <div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div> | string | Formato de contenido de la respuesta.<br/>Valor: applcation/json |
<div class="sc-eCApnc chOOHy">
<div class="sc-iCoGMd dolNKP">
<div class="sc-hKFxyN hutltu">
<table class="sc-hHEiqL iZJLLY">
<tbody>
<tr class="">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="date"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">date</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Fecha en la que se creó la petición en UNIX Timestamp.</p>
</div>
</div>
</div>
</td>
</tr>
<tr class="">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="x-culqi-environment"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">x-culqi-environment</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div><span class="sc-laZMeE dmLkmF"> Enum:</span> <span class="sc-laZMeE sc-ckTSus dmLkmF cDPDUw">"live"</span> <span class="sc-laZMeE sc-ckTSus dmLkmF cDPDUw">"test"</span> </div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Entorno al que se realizó la petición. Ver más.</p>
</div>
</div>
</div>
</td>
</tr>
<tr class="">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="x-culqi-tracking-id"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">x-culqi-tracking-id</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Código de identificación de la petición.</p>
</div>
</div>
</div>
</td>
</tr>
<tr class="">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="x-culqi-version"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">x-culqi-version</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Número de versión del API.</p>
</div>
</div>
</div>
</td>
</tr>
<tr class="last ">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="content-type"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">content-type</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div><span class="sc-laZMeE dmLkmF"> Value:</span> <span class="sc-laZMeE sc-ckTSus dmLkmF cDPDUw">"applcation/json"</span> </div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Formato de contenido de la respuesta.</p>
</div>
</div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
otro ejemplo:
<div class="sc-hKFxyN hutltu_culqi">
<table class="sc-hHEiqL iZJLLY">
<tbody>
<tr class="">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="date"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">date</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt_culqi">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Fecha en la que se creó la petición en UNIX Timestamp.</p>
</div>
</div>
</div>
</td>
</tr>
<tr class="">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="x-culqi-environment"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">x-culqi-environment</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt_culqi">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div><span class="sc-laZMeE dmLkmF"> Enum:</span> <span class="sc-laZMeE sc-ckTSus dmLkmF cDPDUw">"live"</span> <span class="sc-laZMeE sc-ckTSus dmLkmF cDPDUw">"test"</span> </div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Entorno al que se realizó la petición. Ver más.</p>
</div>
</div>
</div>
</td>
</tr>
<tr class="">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="x-culqi-tracking-id"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">x-culqi-tracking-id</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt_culqi">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Código de identificación de la petición.</p>
</div>
</div>
</div>
</td>
</tr>
<tr class="">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="x-culqi-version"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">x-culqi-version</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt_culqi">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Número de versión del API.</p>
</div>
</div>
</div>
</td>
</tr>
<tr class="last ">
<td class="sc-hBMUJo sc-fFSPTT eJvdeH dLEyPf" kind="field" title="content-type"><span class="sc-iemWCZ kMjgQu"></span><span class="property-name">content-type</span>
<div class="sc-oeezt sc-hhIiOg bkbCTW kXduun">required</div>
</td>
<td class="sc-bkbkJK gaTxIt_culqi">
<div>
<div><span class="sc-laZMeE sc-iNiQyp dmLkmF isTLDY"></span><span class="sc-laZMeE sc-jffHpj dmLkmF lVyis">string</span></div>
<div><span class="sc-laZMeE dmLkmF"> Value:</span> <span class="sc-laZMeE sc-ckTSus dmLkmF cDPDUw">"applcation/json"</span> </div>
<div>
<div class="sc-iJCRrE sc-ciSkZP ifDxYI wfptf">
<p>Formato de contenido de la respuesta.</p>
</div>
</div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
# Versionado
Cuando realizamos cambios al API de Culqi que afectan la compatibilidad con versiones anteriores, realizamos lanzamientos de nuevas modificaciones de manera versionada. La última versión fue lanzada el 08-02-2017.
<div class="box info"><div class="content">Los eventos generados por las peticiones al API estarán siempre estructurados de acuerdo a tu versión del API.</div></div>
| Versión API | Fecha | Docs |
| --- | ----------- | ----- |
| v2.0 | 08-02-2017 | [API 2.0](https://apidocs.culqi.com/) |
| v1.2 | 23-08-2016 | [API 1.2](https://culqi.api-docs.io/v1.2) |
| v1.0 | 01-09-2015 | Descontinuada |
**Historial de Cambios**
<br/>
**07-03-2017**
+ Se añadió el parámetro 'validate' para validar tarjeta en [Crear Tarjeta](#operation/crear-tarjeta) (Tarjetas).
+ Se añadió el parámetro 'token_id' en [Actualizar Tarjeta](#operation/actualizar-tarjeta) (Tarjetas).
**15-02-2017**
- Se limitó el Content-Type que consumen y producen los endpoint a application/json.
- Se añadió el filtro de metadata en las operaciones de listado.
# Webhooks
Para usar los eventos listados debes leer nuestra [guía de integración de Webhooks.](https://docs.culqi.com/#/desarrollo/webhooks)
**Lista de Eventos Tokens**
| Evento | Descripción |
| --- | --- |
| token.creation.succeeded | El token fue creado con éxito. |
| token.creation.failed | El token no pudo ser creado. |
| token.expired | El token ha expirado y no puede ser usado para realizar un cargo. |
| token.update.succeeded | La información del token fue actualizada. |
| token.update.failed | La información del token no pudo ser actualizada. |
**Lista de Eventos Cargos**
| Evento | Descripción |
| --- | --- |
| charge.creation.succeeded | El cargo fue procesado con éxito. |
| charge.creation.failed | El cargo no pudo ser procesado y ha sigo denegado. |
| charge.expired | El cargo ha expirado y el monto de la venta devuelto a la tarjeta del cliente. |
| charge.update.succeeded | El cargo fue procesado con éxito. |
| charge.update.fail | La información del cargo no pudo ser actualizada. |
| charge.capture.succeeded | El cargo fue capturado. |
| charge.capture.failed | El cargo no pudo ser capturado. |
**Lista de Eventos Devoluciones**
| Evento | Descripción |
| --- | --- |
| refund.creation.succeeded | La devolución ha sido procesada con éxito. |
| refund.creation.failed | La devolución no pudo ser procesada. |
| refund.update.succeeded | La información de la devolución fue actualizada. |
| refund.update.failed | La información de la devolución no pudo ser actualizada. |
**Lista de Eventos Clientes**
| Evento | Descripción |
| --- | --- |
| customer.creation.succeeded | El cliente fue creado con éxito. |
| customer.creation.failed | El cliente no pudo ser creado. |
| customer.delete.succeeded | El cliente ha sido eliminado con éxito. |
| customer.delete.failed | El cliente no pudo ser eliminado. |
**Lista de Eventos Tarjetas**
| Evento | Descripción |
| --- | --- |
| card.creation.succeeded | La tarjeta fue creada con éxito. |
| card.creation.failed | La tarjeta no pudo ser creada. |
| card.updated.succeeded | La información de la tarjeta fue actualizada con éxito. |
| card.updated.failed | La información de la tarjeta no pudo ser actualizada. |
| card.delete.succeeded | La tarjeta fue eliminada con éxito. |
| card.delete.failed | La tarjeta no pudo ser eliminada. |
**Lista de Eventos Planes**
| Evento | Descripción |
| --- | --- |
| plan.creation.succeeded | El plan fue creado con éxito. |
| plan.creation.failed | El plan no pudo ser creado. |
| plan.update.succeeded | La información del plan fue actualizada con éxito. |
| plan.update.failed | La información del plan no pudo ser actualizada. |
| plan.delete.succeeded | El plan fue eliminado con éxito. |
| plan.delete.failed | El plan no pudo ser eliminado. |
**Lista de Eventos Suscripciones**
| Evento | Descripción |
| --- | --- |
| subscription.creation.succeeded | La suscripción fue creada con éxito. |
| subscription.creation.failed | La suscripción no pudo ser creada. |
| subscription.update.succeeded | La información de la suscripción fue actualizada con éxito. |
| subscription.update.failed | La información de la suscripción no pudo ser actualizada. |
| subscription.cancel.succeeded | La suscripción ha sido cancelada con éxito. |
| subscription.cancel.failed | La suscripción no pudo ser cancelada. |
**Lista de Eventos Órdenes**
| Evento | Descripción |
| --- | --- |
| order.status.changed | La orden cambió de estado. Ver los ejemplos de cambios de estado de órdenes [aquí.](https://docs.culqi.com/#/multipagos/pruebas) |
| order.creation.succeeded | La orden fue creada con éxito. |
servers:
- url: 'https://api.culqi.com'
tags:
- name: Tokens
description: |-
**Tokenización** es el proceso que utiliza Culqi para capturar de manera segura datos sensibles de tarjetas de crédito y débito directamente desde el navegador del cliente. Un token representa la información de la tarjeta y es devuelto a tus servidores para que puedas utilizarlo a través de [Culqi Checkout](https://docs.culqi.com/#/pagos/checkout), [Culqi.JS](https://docs.culqi.com/#/pagos/js) o nuestras bibliotecas para móviles ([iOS](https://docs.culqi.com/#/pagos/ios) y [Android](https://docs.culqi.com/#/pagos/android)). Este método nos asegura que ningún dato de tarjeta toque tus servidores y permite que la integración cumple con la normativa **PCI DSS**.
</br> </br>
Si no deseas hacer uso de los métodos de tokenización disponibles, también puedes crear tokens utilizando la API y tu llave pública. Pero en este caso recuerda que tu empresa será la responsable de cualquier procedimiento requerido por la normativa **PCI DSS**, como por ejemplo el [siguiente autocuestionario](https://www.pcisecuritystandards.org/documents/SAQ_D_v3_Merchant.pdf). A diferencia de Culqi Checkout, Culqi.JS y los SDKs para móviles, la información de tu cliente no será enviada directamente a Culqi así que no podríamos determinar si manejas o guardas esta información con seguridad.
</br>
<div class="box info"><div class="content">Los tokens tienen un tiempo de expiración de 5 minutos por lo que no pueden ser guardados y utilizados más de una vez. Para hacerlos permanentes y generar cargos posteriores o recurrentes, debes <a href="#operation/crear-cliente">crear un cliente</a> y posteriormente <a href="#operation/crear-tarjeta"> crear una tarjeta</a>.</div></div>
# Objeto Token
<SchemaDefinition schemaRef="#/components/schemas/Token" />
- name: Cargos
description: |
Para realizar un cargo a una tarjeta de débito o crédito debes crear un objeto cargo. Adicionalmente puedes consultar, devolver un cargo en particular o listar tu historial de cargos en base a los filtros que desees. Todos los cargos están identificados por un ID.
# Objeto Cargo
<SchemaDefinition schemaRef="#/components/schemas/Cargo" />
- name: Devoluciones
description: |
Una devolución te permite devolver un cargo que ha sido creado previamente y que aún no ha sido devuelto en su totalidad. Los fondos serán devueltos a la tarjeta de crédito o débito que se ha realizado el cargo.
# Objeto Devolucion
<SchemaDefinition schemaRef="#/components/schemas/Devolucion" />
- name: Clientes
description: |
El recurso cliente te permite guardar la información de tus clientes para realizarles cargos recurrentes o posteriores. La API de Culqi permite crear, eliminar y actualizar los datos de tus clientes. Adicionalmente podrás consultar los datos de un cliente en particular o listar a todos tus clientes en base a los filtros que desees.
# Objeto Cliente
<SchemaDefinition schemaRef="#/components/schemas/Cliente" />
- name: Tarjetas
description: |
El objeto Tarjeta se usa para crear cargos posteriores a una tarjeta. Recuerda que un Token por si solo vence a los 5 minutos de creado, pero si lo conviertes en una Tarjeta podrás realizar cargos posteriores. Podrás relacionar múltiples tarjeta al mismo Cliente.
# Objeto Tarjeta
<SchemaDefinition schemaRef="#/components/schemas/Tarjeta" />
- name: Planes
description: |
Un plan de suscripción contiene información acerca del tipo de cargo, frecuencia y monto que quieres cargarle a un Card de manera recurrente. Por ejemplo, podrías configurar un plan básico de S/ 50 mensuales y un plan Premium de S/ 75 mensuales.
# Objeto Plan
<SchemaDefinition schemaRef="#/components/schemas/Plan" />
- name: Suscripciones
description: |
El crear suscripciones te permite realizar cargos recurrentes a la tarjeta de un cliente. Una suscripción relaciona al objeto Customer y al objeto Plan que has creado previamente.
<SchemaDefinition schemaRef="#/components/schemas/Suscripcion" />
- name: Ordenes
description: |
El objeto Orden contiene información de una posible venta. Es usado para el método de pago en efectivo. Una vez es pagada la orden por tu cliente via banco o agente, cambia de estado en el momento de la acción. Con este recurso podrás brindar a tus clientes la opción de pagar sus compras en efectivo.
# Objeto Orden
<SchemaDefinition schemaRef="#/components/schemas/Orden" />
- name: Eventos
description: |
Los eventos son formas de hacerte saber cuando algo sucede en tu cuenta de Culqi. Cuando un evento ocurre, Culqi crea un objeto Evento. Por ejemplo, cuando un cargo es exitoso, Culqi crea el evento charge.succeeded. Adicionalmente, si realizas muchas peticiones al API podría llegar a causar multiples eventos. Por ejemplo, si creas una suscripción para un cliente, recibirás el evento customer.subscription.created y el evento charge.succeeded.
Al igual que los otros recursos del API, puedes consultar un evento particular o listar una serie de eventos directamente desde el API. Adicionalmente, hemos construido un sistema automatizado que enviará eventos directamente a tu servidor: webhooks. Te reconedamos que revises nuestra guía de webhooks para que sepas como configurarlos.
# Objeto Evento
<SchemaDefinition schemaRef="#/components/schemas/Evento" />
paths:
/v2/tokens:
post:
tags:
- Tokens
summary: Crear Token
operationId: crear-token
description: |-
Crear tokens te permitirá obtener información de la tarjeta y utilizarla para [crear un cargo](#operation/crear-cargo) o [crear una tarjeta](#operation/crear-tarjeta).
- Si desarrollas una pagina web deberías crear token utilizando Culqi Checkout o CulqiJS
- Si desarrollas una aplicación móvil deberías crear token utilizando nuestros SDKs para móviles (iOS o Android)
- Si deseas crear el token de manera directa con el API de Culqi debes llenar el siguiente autocuestionario.
parameters:
- schema:
type: string
example: application/json
in: header
name: Content-type
required: true
- schema:
type: string
example: Bearer pk_test_UTCQSGcXW8bCyU59
in: header
name: Authorization
required: true
description: '[Llave pública](#section/Autenticacion)'
requestBody:
content:
application/json:
schema:
type: object
x-examples:
example-1:
card_number: '4111111111111111'
cvv: '123'
expiration_month: '09'
expiration_year: '2020'
email: richard@piedpiper.com
properties:
card_number:
type: string
minLength: 13
maxLength: 16
description: Número de tarjeta.
example: '4111111111111111'
cvv:
type: string
minLength: 1
description: CVV de la tarjeta.
example: '123'
expiration_month:
type: string
minLength: 1
maxLength: 2
example: '09'
description: Mes de expiración de la tarjeta.
expiration_year:
type: string
description: Año de expiración de la tarjeta.
minLength: 4
maxLength: 4
example: '2020'
email:
type: string
description: Dirección de correo electrónico del cliente.
minLength: 5
maxLength: 50
example: ichard@piedpiper.com
metadata:
type: object
description: Informacion adicional que se quiere enviar del token.
example:
dni: '5831543'
required:
- card_number
- cvv
- expiration_month
- expiration_year
- email
examples:
ejemplo 1:
value:
card_number: '4111111111111111'
cvv: '123'
expiration_month: '09'
expiration_year: '2020'
email: ichard@piedpiper.com
metadata:
dni: '5831543'
description: ''
responses:
'201':
description: La petición exitosa.
content:
application/json:
schema:
type: object
properties: {}
examples:
ejemplo 1:
value:
object: token
id: tkn_live_0CjjdWhFpEAZlxlz
type: card
email: richard@piedpiper.com
creation_date: 1476132639
card_number: 442328******1214
last_four: '1214'
active: true
iin:
object: iin
bin: '442328'
card_brand: Visa
card_type: credito
card_category: platinum
issuer:
name: Silicon Valley Bank
country: United States
country_code: US
website: 'https://www.svb.com'
phone_number: +1.800.774.7390
installments_allowed:
- 2
- 4
- 8
- 12
- 24
- 36
client:
ip: 72.229.28.185
ip_country: United States
ip_country_code: US
browser: Google Chrome 56.0.2924.87
device_fingerprint: 6rITdVTYkWfOrss8
device_type: escritorio
metadata:
dni: '5831543'
get:
tags:
- Tokens
summary: Listar Tokens
operationId: get-v2-tokens
responses:
'200':
description: La petición fue exitosa.
content:
application/json:
schema:
type: object
properties: {}
examples:
ejemplo 1:
value:
data: []
paging:
previous: null
next: null
cursors:
before: null
after: null
description: 'Listar tokens te permitirá obtener una serie de tokens existentes. De acuerdo a los filtros que uses los tokens serán ordenados de acuerdo a la fecha de creación, siendo el primero el más reciente.'
parameters:
- schema:
type: string
example: application/json
in: header
name: Content-type
required: true
- schema:
type: string
example: Bearer sk_test_UTCQSGcXW8bCyU59
in: header
name: Authorization
required: true
description: '[Llave privada](#section/Autenticacion)'
- schema:
type: string
example: '1476132639'
in: query
name: creation_date
description: 'Fecha del token en [UNIX Timestamp.](http://www.unixtimestamp.com/)'
- schema:
type: string
in: query
name: creation_date_to
description: Número de tarjeta.
- schema:
type: string
enum:
- Visa
- Mastercard
- Amex
- Diner
in: query
name: card_brand
description: Marca de la tarjeta.
- schema:
type: string
enum:
- credito
- debito
- prepagada
in: query
name: card_type
description: Tipo de tarjeta.
- schema:
type: string
enum:
- escritorio
- movil
- tablet
in: query
name: device_type
description: Tipo de dispositivo.
- schema:
type: string
minLength: 6
maxLength: 6
example: '411111'
in: query
name: bin
description: 'Primeros seis dígitos de la tarjeta expresado en formato [ISO/IEC 7812.](https://es.wikipedia.org/wiki/N%C3%BAmero_de_tarjeta_bancaria)'
- schema:
type: string
example: PE
in: query
name: country_code
description: 'Código del país, en formato ISO-3166 (Alfa 2).'
- schema:
type: string
example: '50'
minLength: 1
maxLength: 100
in: query
name: limit
description: Cantidad exacta de tokens que se quieren listar.
- schema:
type: string
minLength: 25
maxLength: 25
example: tkn_live_7lYOtONQ9LxcgJUW
in: query
name: before
description: El ID del token desde donde se quiere traer los resultados anteriores. No inclusivo.
- schema:
type: string
example: tkn_live_7lYOtOMM6LxcgJUW
minLength: 25
maxLength: 25
in: query
name: after
description: El ID del token desde donde se quiere traer los resultados siguientes. No inclusivo.
requestBody:
content:
application/json:
schema:
type: object
'/v2/tokens/{id}':
get:
tags:
- Tokens
summary: Consultar Token
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties: {}
examples:
ejemplo 1:
value:
object: token
id: tkn_live_701ug3CDNJOAt5Q6
type: card
creation_date: 1486686216000
card_number: 411111******1111
last_four: '1111'
active: false
iin:
object: iin
bin: '411111'
card_brand: Visa
card_type: credit
card_category: Clásica
issuer:
name: 'JPMORGAN CHASE BANK, N.A.'
country: United States
country_code: PE
website: null
phone_number: null
installments_allowed:
- 2
- 4
- 6
- 8
- 10
- 12
client:
ip: 190.235.231.153
ip_country: Perú
ip_country_code: PE
browser: null
device_fingerprint: null
device_type: null
operationId: get-v2-cc
description: 'Consultar el detalle de un [token](#operation/crear-token) utilizando su respectivo ID te permitirá obtener como respuesta el objeto token solicitado. Si la petición es inválida te devolveremos un [error.](#section/Errores)'
parameters:
- schema:
type: string
example: application/json
in: header
name: Content-type
required: true
- schema:
type: string
example: Bearer sk_test_UTCQSGcXW8bCyU59
in: header
name: Authorization
required: true
description: '[Llave privada](#section/Autenticacion)'
parameters:
- schema:
type: string
example: tkn_live_LVNpj300apa78Pjq
minLength: 25
maxLength: 25
name: id
in: path
required: true
description: ID del token a consultar.
patch:
tags:
- Tokens
summary: Actualizar Token
operationId: patch-v2-tokens-id
responses:
'200':
description: La petición fue exitosa.
content:
application/json:
schema:
type: object
properties: {}
examples:
ejemplo 1:
value:
data: []
paging:
previous: null
next: null
cursors:
before: null
after: null
description: Actualizar un token te permitirá agregar o reemplazar información a los valores de la metadata que enviaste a la hora de crearla. Cualquier parámetro o valor no provisto será omitido en los valores de la metadata.
requestBody:
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
metadata:
order_id: '0001'
properties:
metadata:
type: object
description: Informacion adicional que se quiere enviar del token.
example:
dni: '5831543'
cliente_id: 259
parameters:
- schema:
type: string
example: application/json
in: header
name: Content-type
required: true
- schema:
type: string
example: Bearer sk_test_UTCQSGcXW8bCyU59
in: header
name: Authorization
required: true
description: '[Llave privada](#section/Autenticacion)'
/v2/charges:
post:
tags:
- Cargos
summary: Crear cargo
operationId: crear-cargo
responses:
'200':
description: La petición fue exitosa.
content:
application/json:
schema:
type: object
properties: {}
examples:
example-1:
value:
duplicated: false
object: charge
id: chr_live_kEazTaQBDtzNdwFr
amount: 10000
amount_refunded: 0
current_amount: 10000
installments: 0
installments_amount: null
currency: PEN
email: null
description: null
source:
object: token
id: tkn_live_701ug3CDNJOAt5Q6
type: card
creation_date: 1487021247000
card_number: 411111******1111
last_four: '1111'
active: true
iin:
object: iin
bin: '411111'
card_brand: Visa
card_type: credit
card_category: Clásica
issuer:
name: 'JPMORGAN CHASE BANK, N.A.'
country: United States
country_code: PE
website: null
phone_number: null
installments_allowed:
- 2
- 4
- 6
- 8
- 10
- 12
client:
ip: 190.235.231.153