From 2413cf42624ebf1bb3dc5288842c181580fe482f Mon Sep 17 00:00:00 2001 From: Alejandro Ramirez Date: Wed, 10 Dec 2025 17:03:40 -0500 Subject: [PATCH 1/5] feat: Documentation for the Merchant Creation API version 2 (api/v2/merchants) has been added. --- src/assets/apis/three-d-s-server/es.yaml | 175 +++++++++++- .../three-d-s-server/api/merchants/create.mdx | 255 +++++++++++++----- 2 files changed, 362 insertions(+), 68 deletions(-) diff --git a/src/assets/apis/three-d-s-server/es.yaml b/src/assets/apis/three-d-s-server/es.yaml index d0af59dd..266e72aa 100644 --- a/src/assets/apis/three-d-s-server/es.yaml +++ b/src/assets/apis/three-d-s-server/es.yaml @@ -572,7 +572,7 @@ paths: summary: Crear un comercio operationId: post-user responses: - '200': + '200 (V1)': description: OK content: application/json: @@ -716,7 +716,92 @@ paths: code: 1000 data: token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9... - '401': + '200 (V2)': + description: OK + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - OK + reason: + type: string + enum: + - '00' + message: + type: string + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + merchant: + type: object + required: + - id + - name + properties: + id: + type: integer + name: + type: string + token: + type: object + required: + - accessToken + - expiresAt + properties: + accessToken: + type: string + expiresAt: + type: string + format: date-time + branches: + type: array + items: + type: object + required: + - id + - name + - token + properties: + id: + type: integer + name: + type: string + token: + type: object + required: + - accessToken + - expiresAt + properties: + accessToken: + type: string + expiresAt: + type: string + format: date-time + required: + - status + - merchant + examples: + Comercio creado con éxito: + value: + status: + code: 1000 + data: + token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9... + '401 (V1)': description: No autenticado content: application/json: @@ -733,7 +818,48 @@ paths: No autenticado: value: message: Unauthenticated. - '422': + '401 (V2)': + description: No autenticado + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + enum: + - Unauthenticated + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + required: + - status + - reason + - message + - date + examples: + No autenticado: + value: + message: Unauthenticated. + '422 (V1)': description: Mensajes de validación de datos content: application/json: @@ -800,6 +926,43 @@ paths: status: code: 1009 error: The selected subscriptions.0.acquirerBIN is invalid. + '422 (V2)': + description: Mensajes de validación de datos + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + example: 'The branches.0.name has already been taken.' + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + examples: + No autenticado: + value: + message: Unauthenticated. + required: + - status requestBody: content: application/json: @@ -845,12 +1008,12 @@ paths: mcc: type: number description: 'código de categoría de comercial ' - enrollment: - type: boolean - description: 'Indicador que indica si desea enrolar el comercio en la marca' isicClass: type: number description: Código clase CIIU + token: + type: boolean + description: 'Indicador para la creación del token por comercio. Si este campo no se envía, por defecto se tomará como false y no se creará el token (este campo está disponible únicamente en la versión V2 del API).' branch: type: object description: Información de la sucursal diff --git a/src/pages/three-d-s-server/api/merchants/create.mdx b/src/pages/three-d-s-server/api/merchants/create.mdx index 7355d491..37571608 100644 --- a/src/pages/three-d-s-server/api/merchants/create.mdx +++ b/src/pages/three-d-s-server/api/merchants/create.mdx @@ -5,9 +5,9 @@ export const description = 'En esta página, nos sumergiremos en los diferentes export const apiRefs = ['/api/v1/merchants']; # API Comercios ---- -## Crear un comercio {{ id: 'create-a-merchant', tag: 'POST', label: '/api/v1/merchants' }} + +## Crear un comercio {{ id: 'create-a-merchant', tag: 'POST', label: '/api/{version}/merchants' }} @@ -17,51 +17,27 @@ export const apiRefs = ['/api/v1/merchants']; api={props.refs} /> - -
- - ```bash {{ title: 'cURL' }} - curl -X "POST" https://3dss-test.placetopay.com/api/v1/merchants \ - -H "Content-Type: application/json" \ - -H "Accept: application/json" \ - -H "Authorization: Bearer ACCESS_TOKEN" \ - -d '{ - "name": "Comercio uno", - "brand": "Marca comercio uno", - "country": "COL", - "currency": "COP", - "url": "https://www.comercio.com", - "mcc": 742, - "isicClass": 111, - "enrollment": true, - "document": { - "type": "NIT", - "number": "1234567895" - }, - "subscriptions": [ - { - "franchise": "visa", - "acquirerBIN": "411111", - "version": 2, - "merchantCode": "1234" - }, - { - "franchise": "mastercard", - "acquirerBIN": "510510", - "version": 2, - "merchantCode": "1234" - } - ], - "branches": [ - { - "name": "Sucursal uno", - "brand": "Marca de la sucursal uno", + + + ```bash {{ title: 'V1' }} + curl -X "POST" https://3dss-test.placetopay.com/api/v1/merchants \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Authorization: Bearer ACCESS_TOKEN" \ + -d '{ + "name": "Comercio uno", + "brand": "Marca comercio uno", "country": "COL", "currency": "COP", - "url": "https://www.sucursal1.comercio.com", - "enabled": true, + "url": "https://www.comercio.com", + "mcc": 742, + "isicClass": 111, "enrollment": true, + "document": { + "type": "NIT", + "number": "1234567895" + }, "subscriptions": [ { "franchise": "visa", @@ -75,29 +51,126 @@ export const apiRefs = ['/api/v1/merchants']; "version": 2, "merchantCode": "1234" } - ] - }, - { - "name": "Sucursal dos", - "brand": "Marca de la sucursal dos", + ], + "branches": [ + { + "name": "Sucursal uno", + "brand": "Marca de la sucursal uno", + "country": "COL", + "currency": "COP", + "url": "https://www.sucursal1.comercio.com", + "enabled": true, + "enrollment": true, + "subscriptions": [ + { + "franchise": "visa", + "acquirerBIN": "411111", + "version": 2, + "merchantCode": "1234" + }, + { + "franchise": "mastercard", + "acquirerBIN": "510510", + "version": 2, + "merchantCode": "1234" + } + ] + }, + { + "name": "Sucursal dos", + "brand": "Marca de la sucursal dos", + "country": "COL", + "currency": "COP", + "url": "https://www.sucursal2.comercio.com", + "enabled": true, + "subscriptions": [ + { + "franchise": "1", + "acquirerBIN": "411111", + "version": 2, + "merchantCode": "1234" + } + ] + } + ], + "invitations": [] + }' + ``` + ```bash {{ title: 'V2' }} + curl -X "POST" https://3dss-test.placetopay.com/api/v2/merchants \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Authorization: Bearer ACCESS_TOKEN" \ + -d '{ + "name": "Comercio uno", + "brand": "Marca comercio uno", "country": "COL", "currency": "COP", - "url": "https://www.sucursal2.comercio.com", - "enabled": true, + "url": "https://www.comercio.com", + "mcc": 742, + "isicClass": 111, + "document": { + "type": "NIT", + "number": "1234567895" + }, "subscriptions": [ { - "franchise": "1", + "franchise": "visa", "acquirerBIN": "411111", "version": 2, "merchantCode": "1234" + }, + { + "franchise": "mastercard", + "acquirerBIN": "510510", + "version": 2, + "merchantCode": "1234" } - ] - } - ], - "invitations": [] - }' - ``` - + ], + "branches": [ + { + "name": "Sucursal uno", + "brand": "Marca de la sucursal uno", + "country": "COL", + "currency": "COP", + "url": "https://www.sucursal1.comercio.com", + "enabled": true, + "subscriptions": [ + { + "franchise": "visa", + "acquirerBIN": "411111", + "version": 2, + "merchantCode": "1234" + }, + { + "franchise": "mastercard", + "acquirerBIN": "510510", + "version": 2, + "merchantCode": "1234" + } + ] + }, + { + "name": "Sucursal dos", + "brand": "Marca de la sucursal dos", + "country": "COL", + "currency": "COP", + "url": "https://www.sucursal2.comercio.com", + "enabled": true, + "subscriptions": [ + { + "franchise": "1", + "acquirerBIN": "411111", + "version": 2, + "merchantCode": "1234" + } + ] + } + ], + "invitations": [] + }' + ``` + @@ -111,10 +184,10 @@ export const apiRefs = ['/api/v1/merchants']; /> - +
- ```json {{ title: '200' }} + ```json {{ title: '200 (V1)' }} { "status": { "code":1000 @@ -177,12 +250,59 @@ export const apiRefs = ['/api/v1/merchants']; } } ``` - ```json {{ title: '401' }} + + ```json {{ title: '200 (V2)' }} + { + "status": { + "status": "OK", + "reason": "00", + "message": "The request has been successfully processed", + "date": "2025-12-09T20:46:20+00:00" + }, + "merchant": { + "id":1, + "name":"Comercio uno" + }, + "branches":[ + { + "id":1, + "name":"Sucursal uno", + "token": { + "accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...", + "expiresAt": "2028-12-09T20:46:20+00:00", + } + }, + { + "id":2, + "name":"Sucursal dos", + "token": { + "accessToken":"eyJ0eXAiOiJKV19.eyJhdWQiOiIxIiwianRpIjoiMWIyNjgk867nh...............", + "expiresAt": "2028-12-09T20:46:20+00:00", + } + } + ] + + } + ``` + + ```json {{ title: '401 (V1)' }} { "message": "Unauthenticated." } ``` - ```json {{ title: '422' }} + + ```json {{ title: '401 (V2)' }} + { + "status": { + "status": "FAILED", + "reason": "BR", + "message": "Unauthenticated.", + "date": "2025-12-09T20:58:15+00:00" + } + } + ``` + + ```json {{ title: '422 (V1)' }} { "status": { "code": 1003, @@ -190,6 +310,17 @@ export const apiRefs = ['/api/v1/merchants']; } } ``` + + ```json {{ title: '422 (V2)' }} + { + "status": { + "status": "FAILED", + "reason": "BR", + "message": "The branches.0.name has already been taken.", + "date": "2025-12-09T21:00:42+00:00" + } + } + ``` From 2dfcaeefd15920c4d358bcc137cf87424dd04c82 Mon Sep 17 00:00:00 2001 From: Alejandro Ramirez Date: Wed, 10 Dec 2025 17:04:04 -0500 Subject: [PATCH 2/5] feat: English documentation has been added for the Merchant Creation API version 2 (api/v2/merchants) --- src/assets/apis/three-d-s-server/en.yaml | 171 +++++++++++++++++- .../three-d-s-server/api/merchants/create.mdx | 145 ++++++++++++++- 2 files changed, 303 insertions(+), 13 deletions(-) diff --git a/src/assets/apis/three-d-s-server/en.yaml b/src/assets/apis/three-d-s-server/en.yaml index 56904c90..d138245b 100644 --- a/src/assets/apis/three-d-s-server/en.yaml +++ b/src/assets/apis/three-d-s-server/en.yaml @@ -572,7 +572,7 @@ paths: summary: Create a merchant operationId: post-user responses: - '200': + '200 (V1)': description: OK content: application/json: @@ -716,7 +716,92 @@ paths: code: 1000 data: token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9... - '401': + '200 (V2)': + description: OK + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - OK + reason: + type: string + enum: + - '00' + message: + type: string + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + merchant: + type: object + required: + - id + - name + properties: + id: + type: integer + name: + type: string + token: + type: object + required: + - accessToken + - expiresAt + properties: + accessToken: + type: string + expiresAt: + type: string + format: date-time + branches: + type: array + items: + type: object + required: + - id + - name + - token + properties: + id: + type: integer + name: + type: string + token: + type: object + required: + - accessToken + - expiresAt + properties: + accessToken: + type: string + expiresAt: + type: string + format: date-time + required: + - status + - merchant + examples: + Comercio creado con éxito: + value: + status: + code: 1000 + data: + token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9... + '401 (V1)': description: Unauthenticated content: application/json: @@ -733,7 +818,48 @@ paths: Unauthenticated: value: message: Unauthenticated. - '422': + '401 (V2)': + description: Unauthenticated + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + enum: + - Unauthenticated + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + required: + - status + - reason + - message + - date + examples: + No autenticado: + value: + message: Unauthenticated. + '422 (V1)': description: Data validation messages content: application/json: @@ -800,6 +926,39 @@ paths: status: code: 1009 error: The selected subscriptions.0.acquirerBIN is invalid. + '422 (V2)': + description: Data validation messages + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + example: 'The branches.0.name has already been taken.' + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + required: + - status requestBody: content: application/json: @@ -845,12 +1004,12 @@ paths: mcc: type: number description: 'Merchant category code' - enrollment: - type: boolean - description: 'Indicator that specifies whether to enroll the merchant in the brand' isicClass: type: number description: ISIC class code + token: + type: boolean + description: 'Indicator for token creation per merchant. If this field is not sent, it will default to false and the token will not be created (this field is only available in API version V2).' branch: type: object description: Branch information diff --git a/src/pages/en/three-d-s-server/api/merchants/create.mdx b/src/pages/en/three-d-s-server/api/merchants/create.mdx index 17866da5..31415b07 100644 --- a/src/pages/en/three-d-s-server/api/merchants/create.mdx +++ b/src/pages/en/three-d-s-server/api/merchants/create.mdx @@ -5,9 +5,8 @@ export const description = 'This page explores the various 3DSS endpoints you ca export const apiRefs = ['/api/v1/merchants']; # Merchants API ---- -## Create a Merchant {{ id: 'create-a-merchant', tag: 'POST', label: '/api/v1/merchants' }} +## Create a Merchant {{ id: 'create-a-merchant', tag: 'POST', label: '/api/{version}/merchants' }} @@ -20,8 +19,8 @@ export const apiRefs = ['/api/v1/merchants'];
- - ```bash {{ title: 'cURL' }} + + ```bash {{ title: 'V1' }} curl -X "POST" https://3dss-test.placetopay.com/api/v1/merchants \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ @@ -97,6 +96,81 @@ export const apiRefs = ['/api/v1/merchants']; "invitations": [] }' ``` + + ```bash {{ title: 'V2' }} + curl -X "POST" https://3dss-test.placetopay.com/api/v2/merchants \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Authorization: Bearer ACCESS_TOKEN" \ + -d '{ + "name": "Merchant one", + "brand": "Brand merchant one", + "country": "COL", + "currency": "COP", + "url": "https://www.merchant.com", + "mcc": 742, + "isicClass": 111, + "document": { + "type": "NIT", + "number": "1234567895" + }, + "subscriptions": [ + { + "franchise": "visa", + "acquirerBIN": "411111", + "version": 2, + "merchantCode": "1234" + }, + { + "franchise": "mastercard", + "acquirerBIN": "510510", + "version": 2, + "merchantCode": "1234" + } + ], + "branches": [ + { + "name": "Branch one", + "brand": "Branch one brand", + "country": "COL", + "currency": "COP", + "url": "https://www.branch1.merchant.com", + "enabled": true, + "subscriptions": [ + { + "franchise": "visa", + "acquirerBIN": "411111", + "version": 2, + "merchantCode": "1234" + }, + { + "franchise": "mastercard", + "acquirerBIN": "510510", + "version": 2, + "merchantCode": "1234" + } + ] + }, + { + "name": "Branch two", + "brand": "Branch two brand", + "country": "COL", + "currency": "COP", + "url": "https://www.branch2.merchant.com", + "enabled": true, + "subscriptions": [ + { + "franchise": "1", + "acquirerBIN": "411111", + "version": 2, + "merchantCode": "1234" + } + ] + } + ], + "invitations": [] + }' + ``` @@ -114,7 +188,7 @@ export const apiRefs = ['/api/v1/merchants'];
- ```json {{ title: '200' }} + ```json {{ title: '200 (V1)' }} { "status": { "code":1000 @@ -177,12 +251,58 @@ export const apiRefs = ['/api/v1/merchants']; } } ``` - ```json {{ title: '401' }} + + ```json {{ title: '200 (V2)' }} + { + "status": { + "status": "OK", + "reason": "00", + "message": "The request has been successfully processed", + "date": "2025-12-09T20:46:20+00:00" + }, + "merchant": { + "id":1, + "name":"Merchant one", + }, + "branches":[ + { + "id":1, + "name":"Branch one", + "token": { + "accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...", + "expiresAt": "2028-12-09T20:46:20+00:00", + } + }, + { + "id":2, + "name":"Branch two", + "token": { + "accessToken":"eyJ0eXAiOiJKV19.eyJhdWQiOiIxIiwianRpIjoiMWIyNjgk867nh...", + "expiresAt": "2028-12-09T20:46:20+00:00", + } + } + ] + } + ``` + + ```json {{ title: '401 (V1)' }} { "message": "Unauthenticated." } ``` - ```json {{ title: '422' }} + + ```json {{ title: '401 (V2)' }} + { + "status": { + "status": "FAILED", + "reason": "BR", + "message": "Unauthenticated.", + "date": "2025-12-09T20:58:15+00:00" + } + } + ``` + + ```json {{ title: '422 (V1)' }} { "status": { "code": 1003, @@ -190,6 +310,17 @@ export const apiRefs = ['/api/v1/merchants']; } } ``` + + ```json {{ title: '422 (V2)' }} + { + "status": { + "status": "FAILED", + "reason": "BR", + "message": "The branches.0.name has already been taken.", + "date": "2025-12-09T21:00:42+00:00" + } + } + ``` From eb542923c49559c0ab29ced460cef04d5b7b831c Mon Sep 17 00:00:00 2001 From: Alejandro Ramirez Date: Thu, 11 Dec 2025 10:11:28 -0500 Subject: [PATCH 3/5] feat: Documentation for the MerchantBranch Creation API version 2 (api/v2/merchants/{merchant/branches}) has been added. --- src/assets/apis/three-d-s-server/en.yaml | 178 +++++++++++++++++- .../three-d-s-server/api/merchants/branch.mdx | 131 ++++++++++--- 2 files changed, 274 insertions(+), 35 deletions(-) diff --git a/src/assets/apis/three-d-s-server/en.yaml b/src/assets/apis/three-d-s-server/en.yaml index d138245b..a64fa2f0 100644 --- a/src/assets/apis/three-d-s-server/en.yaml +++ b/src/assets/apis/three-d-s-server/en.yaml @@ -1172,9 +1172,6 @@ paths: minLength: 1 maxLength: 90 description: Website URL for the branch - enrollment: - type: boolean - description: 'Indicator that specifies whether to enroll the branch in the brand @deprecated' subscriptions: type: array uniqueItems: true @@ -1227,7 +1224,7 @@ paths: properties: { } description: Send the required fields for the API to add branches to a merchant. responses: - '200': + '200 (V1)': description: OK content: application/json: @@ -1251,6 +1248,8 @@ paths: - name - brand - url + - token + - expires_at properties: id: type: integer @@ -1320,7 +1319,69 @@ paths: name: City B Office brand: Company City B url: 'https://company-b.com' - '401': + '200 (V2)': + description: OK + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - OK + reason: + type: string + enum: + - '00' + message: + type: string + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + branches: + type: array + items: + type: object + required: + - id + - name + - token + - url + properties: + id: + type: integer + name: + type: string + brand: + type: string + url: + type: string + token: + type: array + required: + - accessToken + - expiresAt + properties: + accessToken: + type: string + expiresAt: + type: string + format: date-time + required: + - status + - branches + '401 (V1)': description: Unauthenticated content: application/json: @@ -1337,7 +1398,44 @@ paths: Unauthenticated: value: message: Unauthenticated. - '404': + '401 (V2)': + description: Unauthenticated + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + enum: + - Unauthenticated + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + required: + - status + - reason + - message + - date + '404 (V1)': description: Merchant does not exist content: application/json: @@ -1364,7 +1462,40 @@ paths: status: code: 1010 error: The merchant does not exist - '422': + '404 (V2)': + description: Merchant does not exist + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + example: 'The merchant does not exist' + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + required: + - status + '422 (V1)': description: Data validation messages content: application/json: @@ -1411,6 +1542,39 @@ paths: status: code: 1004 error: The branches.0.url must be a valid URL. + '422 (V2)': + description: Data validation messages + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + example: 'The branches.0.name has already been taken.' + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + required: + - status description: Add branches to a merchant parameters: - schema: diff --git a/src/pages/en/three-d-s-server/api/merchants/branch.mdx b/src/pages/en/three-d-s-server/api/merchants/branch.mdx index d5f6ec46..8a29139c 100644 --- a/src/pages/en/three-d-s-server/api/merchants/branch.mdx +++ b/src/pages/en/three-d-s-server/api/merchants/branch.mdx @@ -4,7 +4,6 @@ export const description = export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; # Branches API ---- ## Add branches to a merchant {{ id: 'add-branches', tag: 'POST', label: '/api/v1/merchants/merchantID/branches' }} @@ -21,7 +20,7 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; - ```bash {{ title: 'cURL' }} + ```bash {{ title: 'V1' }} curl -X "POST" https://3dss-test.placetopay.com/api/v1/merchants/{merchantID}/branches \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ @@ -42,7 +41,6 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; "currency": "COP", "url": "https://example-dos.com" "enabled": true, - "enrollment": true, "subscriptions": [ { "franchise": "visa", @@ -61,6 +59,45 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; ] }' ``` + ```bash {{ title: 'V2' }} + curl -X "POST" https://3dss-test.placetopay.com/api/v2/merchants/{merchantID}/branches \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Authorization: Bearer ACCESS_TOKEN" \ + -d '{ + "branches": [ + { + "name": "Medellin Office", + "brand": "Evertec Medellin", + "country": "COL", + "currency": "COP", + "url": "https://example-uno.com" + }, + { + "name": "Bogotá Office", + "brand": "Evertec Bogotá", + "country": "COL", + "currency": "COP", + "url": "https://example-dos.com" + "enabled": true, + "subscriptions": [ + { + "franchise": "visa", + "acquirerBIN": "454819", + "version": 2, + "merchantCode": "1234" + }, + { + "franchise": "mastercard", + "acquirerBIN": "510510", + "version": 2, + "merchantCode": "3064" + } + ] + } + ] + }' + ``` @@ -78,7 +115,7 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches'];
- ```json {{ title: '200' }} + ```json {{ title: '200 (V1)' }} { "status": { "code": 1000 @@ -118,57 +155,95 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; ] } ``` - ```json {{ title: '401' }} + ```json {{ title: '200 (V2)' }} + { + "status": { + "status": "OK", + "reason": "00", + "message": "The request has been successfully processed", + "date": "2025-12-10T22:36:18+00:00" + }, + "branches": [ + { + "id": 1, + "name": "City A Office", + "brand": "Company City A", + "url": "https://company-a.com" + "token": { + "accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...", + "expiresAt": "2028-12-09T20:46:20+00:00", + } + }, + { + "id": 2, + "name": "City B Office", + "brand": "Company City B", + "url": "https://company-b.com" + "token": { + "accessToken":"eV19eyJhdWQiOiIxIiwianRpIjoiMWIyNjgk867nh...", + "expiresAt": "2028-12-09T20:46:20+00:00", + } + } + ] + } + ``` + ```json {{ title: '401 (V1)' }} { "message": "Unauthenticated." } ``` - ```json {{ title: '404' }} + ```json {{ title: '401 (V2)' }} { - "status": { - "code": 1010, - "error": "The merchant does not exist" - } + "status": { + "status": "FAILED", + "reason": "BR", + "message": "Unauthenticated.", + "date": "2025-12-09T20:58:15+00:00" + } } ``` - ```json {{ title: '422' }} + ```json {{ title: '404 (V1)' }} { "status": { - "code": 1001, - "error": "The branches field is required." + "code": 1010, + "error": "The merchant does not exist" } } ``` - ```json {{ title: '422' }} + ```json {{ title: '404 (V2)' }} { - "status": { - "code": 1002, - "error": "The branches.0.country must be 3 characters." - } + "status": { + "status": "FAILED", + "reason": "BR", + "message": "The merchant does not exist", + "date": "2025-12-09T21:00:42+00:00" + } } ``` ```json {{ title: '422' }} { "status": { - "code": 1002, - "error": "The selected branches.0.currency is invalid." + "code": 1001, + "error": "The branches field is required." } } ``` - ```json {{ title: '422' }} + ```json {{ title: '422 (V1)' }} { "status": { - "code": 1004, - "error": "The branches.0.name has already been taken." + "code": 1002, + "error": "The branches.0.country is required." } } ``` - ```json {{ title: '422' }} + ```json {{ title: '422 (V2)' }} { - "status": { - "code": 1004, - "error": "The branches.0.url must be a valid URL." - } + "status": { + "status": "FAILED", + "reason": "BR", + "message": "The branches.0.name field is required.", + "date": "2025-12-09T21:00:42+00:00" + } } ``` From 2a139e3f30897aef3e53f57e90df3585631a45c4 Mon Sep 17 00:00:00 2001 From: Alejandro Ramirez Date: Thu, 11 Dec 2025 10:12:41 -0500 Subject: [PATCH 4/5] feat: English documentation has been added for the MerchantBranch Creation API version 2 (api/v2/merchants/{merchant}/branches) --- src/assets/apis/three-d-s-server/es.yaml | 223 ++++++++++++++---- .../three-d-s-server/api/merchants/branch.mdx | 135 ++++++++--- 2 files changed, 281 insertions(+), 77 deletions(-) diff --git a/src/assets/apis/three-d-s-server/es.yaml b/src/assets/apis/three-d-s-server/es.yaml index 266e72aa..5bcab6de 100644 --- a/src/assets/apis/three-d-s-server/es.yaml +++ b/src/assets/apis/three-d-s-server/es.yaml @@ -1176,9 +1176,6 @@ paths: minLength: 1 maxLength: 90 description: Url de la página web de la sucursal - enrollment: - type: boolean - description: 'Indicador que indica si desea enrolar el comercio en la marca @deprecated' subscriptions: type: array uniqueItems: true @@ -1231,7 +1228,7 @@ paths: properties: { } description: Envíe los campos necesarios para que la API agregue las sucursales a un comercio. responses: - '200': + '200 (V1)': description: OK content: application/json: @@ -1255,6 +1252,8 @@ paths: - name - brand - url + - token + - expires_at properties: id: type: integer @@ -1270,43 +1269,6 @@ paths: expires_at: type: string format: date-time - enrollment: - type: object - properties: - mastercard: - type: object - required: - - uuid - - messageType - - data - - subscriptionId - properties: - uuid: - type: string - format: uuid - messageType: - type: string - data: - type: object - properties: - acquirerBIN: - type: string - acquirerICA: - type: string - acquirerName: - type: string - acquirerCID: - type: string - status: - type: string - reason: - type: string - modelId: - type: string - modelName: - type: string - subscriptionId: - type: integer required: - status - data @@ -1324,7 +1286,69 @@ paths: name: Oficina Ciudad B brand: Compañía Ciudad B url: 'https://company-b.com' - '401': + '200 (V2)': + description: OK + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - OK + reason: + type: string + enum: + - '00' + message: + type: string + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + branches: + type: array + items: + type: object + required: + - id + - name + - token + - url + properties: + id: + type: integer + name: + type: string + brand: + type: string + url: + type: string + token: + type: array + required: + - accessToken + - expiresAt + properties: + accessToken: + type: string + expiresAt: + type: string + format: date-time + required: + - status + - branches + '401 (V1)': description: No autenticado content: application/json: @@ -1341,7 +1365,48 @@ paths: No autenticado: value: message: Unauthenticated. - '404': + '401 (V2)': + description: No autenticado + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + enum: + - Unauthenticated + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + required: + - status + - reason + - message + - date + examples: + No autenticado: + value: + message: Unauthenticated. + '404 (V1)': description: El comercio no existe content: application/json: @@ -1368,7 +1433,40 @@ paths: status: code: 1010 error: The merchant does not exist - '422': + '404 (V2)': + description: El comercio no existe + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + example: 'The merchant does not exist' + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + required: + - status + '422 (V1)': description: Mensajes de validación de datos content: application/json: @@ -1415,6 +1513,43 @@ paths: status: code: 1004 error: The branches.0.url must be a valid URL. + '422 (V2)': + description: Mensajes de validación de datos + content: + application/json: + schema: + description: '' + type: object + properties: + status: + type: object + required: + - status + - reason + - message + - date + properties: + status: + type: string + enum: + - FAILED + reason: + type: string + enum: + - BR + message: + type: string + example: 'The branches.0.name has already been taken.' + date: + type: string + format: date-time + example: '2025-12-09T12:00:00Z' + examples: + No autenticado: + value: + message: Unauthenticated. + required: + - status description: Agregar sucursales a un comercio parameters: - schema: diff --git a/src/pages/three-d-s-server/api/merchants/branch.mdx b/src/pages/three-d-s-server/api/merchants/branch.mdx index b324b816..3c1c65e1 100644 --- a/src/pages/three-d-s-server/api/merchants/branch.mdx +++ b/src/pages/three-d-s-server/api/merchants/branch.mdx @@ -4,9 +4,8 @@ export const description = export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; # API Sucursales ---- -## Agregar sucursales a un comercio {{ id: 'add-branches', tag: 'POST', label: '/api/v1/merchants/merchantID/branches' }} +## Agregar sucursales a un comercio {{ id: 'add-branches', tag: 'POST', label: '/api/{version}/merchants/merchantID/branches' }} @@ -20,8 +19,8 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; /> - - ```bash {{ title: 'cURL' }} + + ```bash {{ title: 'V1' }} curl -X "POST" https://3dss-test.placetopay.com/api/v1/merchants/{merchantID}/branches \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ @@ -61,6 +60,46 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; ] }' ``` + + ```bash {{ title: 'V2' }} + curl -X "POST" https://3dss-test.placetopay.com/api/v2/merchants/{merchantID}/branches \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Authorization: Bearer ACCESS_TOKEN" \ + -d '{ + "branches": [ + { + "name": "Oficina Medellin", + "brand": "Evertec Medellin", + "country": "COL", + "currency": "COP", + "url": "https://example-uno.com" + }, + { + "name": "Oficina Bogotá", + "brand": "Evertec Bogotá", + "country": "COL", + "currency": "COP", + "url": "https://example-dos.com" + "enabled": true, + "subscriptions": [ + { + "franchise": "visa", + "acquirerBIN": "454819", + "version": 2, + "merchantCode": "1234" + }, + { + "franchise": "mastercard", + "acquirerBIN": "510510", + "version": 2, + "merchantCode": "3064" + } + ] + } + ] + }' + ``` @@ -78,7 +117,7 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches'];
- ```json {{ title: '200' }} + ```json {{ title: '200 (V1)' }} { "status": { "code": 1000 @@ -118,57 +157,87 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; ] } ``` - ```json {{ title: '401' }} + ```json {{ title: '200 (V2)' }} { - "message": "Unauthenticated." + "status": { + "status": "OK", + "reason": "00", + "message": "The request has been successfully processed", + "date": "2025-12-10T22:36:18+00:00" + }, + "branches": [ + { + "id": 1, + "name": "Oficina Ciudad A", + "brand": "Compañía Ciudad A", + "url": "https://company-a.com", + "token": { + "accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...", + "expiresAt": "2028-12-09T20:46:20+00:00", + } + }, + { + "id": 2, + "name": "Oficina Ciudad B", + "brand": "Compañía Ciudad B", + "url": "https://company-b.com", + "token": { + "accessToken":"eV19eyJhdWQiOiIxIiwianRpIjoiMWIyNjgk867nh...", + "expiresAt": "2028-12-09T20:46:20+00:00", + } + } + ] } ``` - ```json {{ title: '404' }} + ```json {{ title: '401 (V1)' }} { - "status": { - "code": 1010, - "error": "The merchant does not exist" - } + "message": "Unauthenticated." } ``` - ```json {{ title: '422' }} + ```json {{ title: '401 (V2)' }} { - "status": { - "code": 1001, - "error": "The branches field is required." - } + "status": { + "status": "FAILED", + "reason": "BR", + "message": "Unauthenticated.", + "date": "2025-12-09T20:58:15+00:00" + } } ``` - ```json {{ title: '422' }} + ```json {{ title: '404 (V1)' }} { "status": { - "code": 1002, - "error": "The branches.0.country must be 3 characters." + "code": 1010, + "error": "The merchant does not exist" } } ``` - ```json {{ title: '422' }} + ```json {{ title: '404 (V2)' }} { - "status": { - "code": 1002, - "error": "The selected branches.0.currency is invalid." - } + "status": { + "status": "FAILED", + "reason": "BR", + "message": "The merchant does not exist", + "date": "2025-12-09T21:00:42+00:00" + } } ``` - ```json {{ title: '422' }} + ```json {{ title: '422 (V1)' }} { "status": { - "code": 1004, - "error": "The branches.0.name has already been taken." + "code": 1001, + "error": "The branches.0.name field is required." } } ``` - ```json {{ title: '422' }} + ```json {{ title: '422 (V2)' }} { - "status": { - "code": 1004, - "error": "The branches.0.url must be a valid URL." - } + "status": { + "status": "FAILED", + "reason": "BR", + "message": "The branches.0.name field is required.", + "date": "2025-12-09T21:00:42+00:00" + } } ``` From e6098f2ac49a87787fb29371fbb2ef260a9fb496 Mon Sep 17 00:00:00 2001 From: Alejandro Ramirez Date: Thu, 15 Jan 2026 17:01:08 -0500 Subject: [PATCH 5/5] refactor: createToken field is documented --- src/assets/apis/three-d-s-server/en.yaml | 10 ++++++++-- src/assets/apis/three-d-s-server/es.yaml | 10 ++++++++-- src/pages/en/three-d-s-server/api/merchants/branch.mdx | 4 +++- src/pages/en/three-d-s-server/api/merchants/create.mdx | 2 ++ src/pages/three-d-s-server/api/merchants/branch.mdx | 4 +++- src/pages/three-d-s-server/api/merchants/create.mdx | 2 ++ 6 files changed, 26 insertions(+), 6 deletions(-) diff --git a/src/assets/apis/three-d-s-server/en.yaml b/src/assets/apis/three-d-s-server/en.yaml index f4e02d3e..d7898259 100644 --- a/src/assets/apis/three-d-s-server/en.yaml +++ b/src/assets/apis/three-d-s-server/en.yaml @@ -1016,10 +1016,10 @@ paths: isicClass: type: number description: ISIC class code - token: + createToken: type: boolean description: 'Indicator for token creation per merchant. If this field is not sent, it will default to false and the token will not be created (this field is only available in API version V2).' - branch: + branches: type: object description: Branch information required: @@ -1063,6 +1063,9 @@ paths: * The URL must not include fragments. (hash or anchors, https://example.com`#section`). * The URL must have a defined host. (https://`path`) * The host cannot be an IP address. (https://`192.168.1.1`) + createToken: + type: boolean + description: 'Indicator for token creation per branch. If this field is not sent, it will default to false and the token will not be created (this field is only available in API version V2).' subscriptions: type: array uniqueItems: true @@ -1205,6 +1208,9 @@ paths: * The URL must not include fragments. (hash or anchors, https://example.com`#section`). * The URL must have a defined host. (https://`path`) * The host cannot be an IP address. (https://`192.168.1.1`) + createToken: + type: boolean + description: 'Indicator for token creation per branch. If this field is not sent, it will default to false and the token will not be created (this field is only available in API version V2).' enrollment: type: boolean description: 'Indicator that specifies whether to enroll the branch in the brand @deprecated' diff --git a/src/assets/apis/three-d-s-server/es.yaml b/src/assets/apis/three-d-s-server/es.yaml index 9bb5c19f..cea82981 100644 --- a/src/assets/apis/three-d-s-server/es.yaml +++ b/src/assets/apis/three-d-s-server/es.yaml @@ -1020,10 +1020,10 @@ paths: isicClass: type: number description: Código clase CIIU - token: + createToken: type: boolean description: 'Indicador para la creación del token por comercio. Si este campo no se envía, por defecto se tomará como false y no se creará el token (este campo está disponible únicamente en la versión V2 del API).' - branch: + branches: type: object description: Información de la sucursal required: @@ -1067,6 +1067,9 @@ paths: * La URL no debe incluir fragmentos (hash o anclas, https://example.com`#section`). * La URL debe tener un host definido. (https://`path`) * El host no puede ser una dirección IP. (https://`192.168.1.1`) + createToken: + type: boolean + description: 'Indicador para la creación del token por sucursal. Si este campo no se envía, por defecto se tomará como false y no se creará el token (este campo está disponible únicamente en la versión V2 del API).' subscriptions: type: array uniqueItems: true @@ -1209,6 +1212,9 @@ paths: * La URL no debe incluir fragmentos (hash o anclas, https://example.com`#section`). * La URL debe tener un host definido. (https://`path`) * El host no puede ser una dirección IP. (https://`192.168.1.1`) + createToken: + type: boolean + description: 'Indicador para la creación del token por sucursal. Si este campo no se envía, por defecto se tomará como false y no se creará el token (este campo está disponible únicamente en la versión V2 del API).' enrollment: type: boolean description: 'Indicador que indica si desea enrolar el comercio en la marca @deprecated' diff --git a/src/pages/en/three-d-s-server/api/merchants/branch.mdx b/src/pages/en/three-d-s-server/api/merchants/branch.mdx index 8a29139c..9aa1249a 100644 --- a/src/pages/en/three-d-s-server/api/merchants/branch.mdx +++ b/src/pages/en/three-d-s-server/api/merchants/branch.mdx @@ -71,7 +71,8 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; "brand": "Evertec Medellin", "country": "COL", "currency": "COP", - "url": "https://example-uno.com" + "url": "https://example-uno.com", + "createToken": true, }, { "name": "Bogotá Office", @@ -80,6 +81,7 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; "currency": "COP", "url": "https://example-dos.com" "enabled": true, + "createToken": true, "subscriptions": [ { "franchise": "visa", diff --git a/src/pages/en/three-d-s-server/api/merchants/create.mdx b/src/pages/en/three-d-s-server/api/merchants/create.mdx index 31415b07..59884e46 100644 --- a/src/pages/en/three-d-s-server/api/merchants/create.mdx +++ b/src/pages/en/three-d-s-server/api/merchants/create.mdx @@ -136,6 +136,7 @@ export const apiRefs = ['/api/v1/merchants']; "currency": "COP", "url": "https://www.branch1.merchant.com", "enabled": true, + "createToken": true, "subscriptions": [ { "franchise": "visa", @@ -158,6 +159,7 @@ export const apiRefs = ['/api/v1/merchants']; "currency": "COP", "url": "https://www.branch2.merchant.com", "enabled": true, + "createToken": true, "subscriptions": [ { "franchise": "1", diff --git a/src/pages/three-d-s-server/api/merchants/branch.mdx b/src/pages/three-d-s-server/api/merchants/branch.mdx index 3c1c65e1..2e8e983e 100644 --- a/src/pages/three-d-s-server/api/merchants/branch.mdx +++ b/src/pages/three-d-s-server/api/merchants/branch.mdx @@ -73,7 +73,8 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; "brand": "Evertec Medellin", "country": "COL", "currency": "COP", - "url": "https://example-uno.com" + "url": "https://example-uno.com", + "createToken": true, }, { "name": "Oficina Bogotá", @@ -82,6 +83,7 @@ export const apiRefs = ['/api/v1/merchants/{merchantID}/branches']; "currency": "COP", "url": "https://example-dos.com" "enabled": true, + "createToken": true, "subscriptions": [ { "franchise": "visa", diff --git a/src/pages/three-d-s-server/api/merchants/create.mdx b/src/pages/three-d-s-server/api/merchants/create.mdx index 37571608..a2f35fe4 100644 --- a/src/pages/three-d-s-server/api/merchants/create.mdx +++ b/src/pages/three-d-s-server/api/merchants/create.mdx @@ -135,6 +135,7 @@ export const apiRefs = ['/api/v1/merchants']; "currency": "COP", "url": "https://www.sucursal1.comercio.com", "enabled": true, + "createToken": true, "subscriptions": [ { "franchise": "visa", @@ -157,6 +158,7 @@ export const apiRefs = ['/api/v1/merchants']; "currency": "COP", "url": "https://www.sucursal2.comercio.com", "enabled": true, + "createToken": true, "subscriptions": [ { "franchise": "1",