diff --git a/v0/catalog/ageverification/age_verification_openapi.yaml b/v0/catalog/ageverification/age_verification_openapi.yaml new file mode 100644 index 0000000..1829e69 --- /dev/null +++ b/v0/catalog/ageverification/age_verification_openapi.yaml @@ -0,0 +1,452 @@ +openapi: 3.0.3 +info: + title: Age Verification + termsOfService: http://swagger.io/terms/ + contact: + name: Telefónica Open Gateway DevRel + url: https://opengateway.telefonica.com/en/developer-hub + email: devrel@telefonica.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + + version: "0.1" + +servers: + - url: "{host}/kyc-age-verification/v0.1" + variables: + host: + default: sandbox.opengateway.telefonica.com/apigateway + description: API gateway URL + +tags: + - name: Verify a customer age + description: Operations to verify the age of a user. + +paths: + /verify: + post: + summary: Verify age threshold v0.1 + tags: + - Verify a customer age + description: | + Verify that the age of the subscriber associated with a phone number is equal to or greater than the specified age threshold value. + + As it is possible that the person holding the contract and the end-user of the subscription may not be the same, the endpoint also admits a list of optional properties to be included in the request to improve the identification. The response may optionally include the `identityMatchScore` property with a value that indicates how certain it is that the information returned relates to the person that the API Client is requesting. To increase the reliability of the information returned, the API Provider may include in the response the `verifiedStatus` property, indicating whether the identity information in its possession has been verified against an identification document legally accepted as an age verification document. + + If the API Client indicates request properties `includeContentLock` or `includeParentalControl` with value `true` and the API Provider implements this functionality, then the response will also include `contentLock` and `parentalControl` properties to indicate if the subscription has any kind of content filtering enabled. On the other hand, if the request properties are not included or the API Client specifies value `false`, then the response properties will not be returned. If the API Provider doesn't implement this functionality, request properties will be ignored and response properties won't be returned in any case. + + Check the [Authorization guide](/docs/authorization) on how to get an OAuth2 token, with the following scope: + + `dpv:FraudPreventionAndDetection kyc-age-verification:verify` + + Create an app on our [Sandbox](/docs/sandbox) to get credentials and [retrieve tokens](/reference/authorize) so you can perform API calls to our operators' production environments, or use the following convenience token to test in mock mode: + + `mock_sandbox_access_token` + operationId: verifyAge + security: + - openId: + - kyc-age-verification:verify + parameters: + - $ref: '#/components/parameters/x-correlator' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/VerifyRequestBody' + examples: + Two-Legged Access Token Example: + value: + ageThreshold: 18 + phoneNumber: '+34629255833' # Note: Only required in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, do not include phoneNumber + idDocument: 66666666q + name: Federica Sanchez Arjona + givenName: Federica + familyName: Sanchez Arjona + middleNames: Sanchez + familyNameAtBirth: YYYY + birthdate: '1978-08-22' + email: "federicaSanchez.Arjona@example.com" + includeContentLock: true + includeParentalControl: true + Three-Legged Access Token Example: + value: + ageThreshold: 18 + idDocument: 66666666q + name: Federica Sanchez Arjona + givenName: Federica + familyName: Sanchez Arjona + middleNames: Sanchez + familyNameAtBirth: YYYY + birthdate: '1978-08-22' + email: "federicaSanchez.Arjona@gmail.com" + includeContentLock: true + includeParentalControl: true + + responses: + '200': + description: OK + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/VerifyResponseBody' + examples: + KYC_200Example: + value: + ageCheck: "true" + verifiedStatus: true + identityMatchScore: 90 + contentLock: "false" + parentalControl: "true" + "400": + $ref: '#/components/responses/Generic400' + "401": + $ref: '#/components/responses/Generic401' + "403": + $ref: '#/components/responses/Generic403' + "404": + $ref: '#/components/responses/Generic404' + "422": + $ref: '#/components/responses/Generic422' + +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + pattern: ^[a-zA-Z0-9-]{0,55}$ + + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + pattern: ^[a-zA-Z0-9-]{0,55}$ + example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" + + schemas: + VerifyRequestBody: + type: "object" + description: Request to verify the age threshold provided. + required: + - ageThreshold + properties: + ageThreshold: + $ref: "#/components/schemas/AgeThreshold" + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + idDocument: + $ref: "#/components/schemas/IdDocument" + name: + $ref: "#/components/schemas/Name" + givenName: + $ref: "#/components/schemas/GivenName" + familyName: + $ref: "#/components/schemas/FamilyName" + middleNames: + $ref: "#/components/schemas/MiddleNames" + familyNameAtBirth: + $ref: "#/components/schemas/FamilyNameAtBirth" + birthdate: + $ref: "#/components/schemas/Birthdate" + email: + $ref: "#/components/schemas/Email" + includeContentLock: + $ref: "#/components/schemas/IncludeContentLock" + includeParentalControl: + $ref: "#/components/schemas/IncludeParentalControl" + + AgeThreshold: + type: "integer" + minimum: 0 + maximum: 120 + description: The age to be verified. The indicated range is a global definition of maximum and minimum values allowed to be requested. It is important to note that this range might be more restrictive in some implementations due to local regulations of a country i.e. A country does not allow to request for an age under 18. This limitation must be informed during the onboarding process. + + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + + IdDocument: + type: "string" + description: Id number associated to the official identity document in the country. It may contain alphanumeric characters. + + Name: + type: "string" + description: Complete name of the customer, usually composed of first/given name and last/family/sur- name in a country. Depending on the country, the order of first/give name and last/family/sur- name varies, and middle name could be included. It can use givenName, middleNames, familyName and/or familyNameAtBirth. For example, in ESP, name+familyName; in NLD, it can be name+middleNames+familyName or name+middleNames+familyNameAtBirth, etc. + + GivenName: + type: "string" + description: First/given name or compound first/given name of the customer. + + FamilyName: + type: "string" + description: Last name, family name, or surname of the customer. + + MiddleNames: + type: "string" + description: Middle name/s of the customer. + + FamilyNameAtBirth: + type: "string" + description: Last/family/sur- name at birth of the customer. + + Birthdate: + type: string + format: date + description: The birthdate of the customer, in RFC 3339 / ISO 8601 calendar date format (YYYY-MM-DD). + + Email: + type: string + format: email + description: Email address of the customer in the RFC specified format (local-part@domain). + + IncludeContentLock: + type: boolean + default: false + description: If this parameter is included in the request with value `true`, the response property `contentLock` will be returned. If it is not included or its value is `false`, the response property will not be returned. + + IncludeParentalControl: + type: boolean + default: false + description: If this parameter is included in the request with value `true`, the response property `parentalControl` will be returned. If it is not included or its value is `false`, the response property will not be returned. + + VerifyResponseBody: + type: "object" + description: Response to an age verification request + required: + - ageCheck + properties: + ageCheck: + $ref: "#/components/schemas/AgeCheck" + verifiedStatus: + $ref: "#/components/schemas/VerifiedStatus" + identityMatchScore: + $ref: "#/components/schemas/IdentityMatchScore" + contentLock: + $ref: "#/components/schemas/ContentLock" + parentalControl: + $ref: "#/components/schemas/ParentalControl" + + AgeCheck: + type: "string" + description: Indicate `"true"` when the age of the user is the same age or older than the age threshold (age >= age threshold), and `"false"` if not (age < age threshold). If the API Provider doesn't have enough information to perform the validation, a `not_available` can be returned. + enum: + - 'true' + - 'false' + - 'not_available' + + VerifiedStatus: + type: "boolean" + description: Indicate `true` if the information provided has been compared against information based on an identification document legally accepted as an age verification document, otherwise indicate `false`. + + IdentityMatchScore: + type: "integer" + minimum: 0 + maximum: 100 + description: The overall score of identity information available in the API Provider, information either provided in the request body comparing it to the one that the API Provider holds or directly using internal API Provider's information. It is optional for the API Provider to return the Identity match score. + + ContentLock: + type: "string" + description: Indicate `"true"` if the subscription associated with the phone number has any kind of content lock (i.e certain web content blocked) and `"false"` if not. If the information is not available the value `not_available` can be returned. + enum: + - 'true' + - 'false' + - 'not_available' + + ParentalControl: + type: "string" + description: Indicate `"true"` if the subscription associated with the phone number has any kind of parental control activated and `"false"` if not. If the information is not available the value `not_available` can be returned. + enum: + - 'true' + - 'false' + - 'not_available' + + ErrorInfo: + type: "object" + required: + - status + - code + - message + properties: + status: + type: "integer" + description: HTTP response status code + code: + type: "string" + description: Code given to this error + message: + type: "string" + description: Detailed error description + + responses: + Generic400: + description: Bad Request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + - OUT_OF_RANGE + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + + Generic401: + description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 401 + code: + enum: + - UNAUTHENTICATED + - AUTHENTICATION_REQUIRED + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + + Generic403: + description: Forbidden + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + + Generic404: + description: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 404 + code: + enum: + - IDENTIFIER_NOT_FOUND + examples: + GENERIC_404_IDENTIFIER_NOT_FOUND: + description: The phone number is not associated with a CSP customer account + value: + status: 404 + code: IDENTIFIER_NOT_FOUND + message: The phone number provided is not associated with a customer account + + Generic422: + description: Unprocessable Content + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 422 + code: + enum: + - SERVICE_NOT_APPLICABLE + - MISSING_IDENTIFIER + - UNNECESSARY_IDENTIFIER + examples: + GENERIC_422_SERVICE_NOT_APPLICABLE: + description: Service is not applicable for the provided phone number + value: + status: 422 + code: SERVICE_NOT_APPLICABLE + message: The service is not applicable for the provided phone number + GENERIC_422_MISSING_IDENTIFIER: + description: No phone number has been provided either explicitly or associated with the access token + value: + status: 422 + code: MISSING_IDENTIFIER + message: No phone number has been provided + GENERIC_422_UNNECESSARY_IDENTIFIER: + description: An explicit phone number has been provided when one is already associated with the access token + value: + status: 422 + code: UNNECESSARY_IDENTIFIER + message: An explicit phone number has been provided when one is already associated with the access token diff --git a/v0/catalog/ageverification/samplecode_ageverification.md b/v0/catalog/ageverification/samplecode_ageverification.md new file mode 100644 index 0000000..5ed7dcc --- /dev/null +++ b/v0/catalog/ageverification/samplecode_ageverification.md @@ -0,0 +1,154 @@ +--- +title: Sample code for Age Verification +excerpt: The following samples show how to use the [Open Gateway Age Verification API](https://opengateway.telefonica.com/en/apis/age-verification) to check if a subscriber meets a required age threshold, optionally including content lock or parental control information. +category: 681879c3afc1a0003709c745 +--- + +The following code shows, for didactic purposes, a hypothetical or sample SDK, in several programming languages, from a generic Open Gateway's channel partner, also known as aggregator. + +The final implementation will depend on the channel partner's development tools offering. Sample code on how to consume the API without an SDK, directly with HTTP requests, is also provided. + +> 📘 Want to try it before coding? +> Check the [API interactive reference](https://developers.opengateway.telefonica.com/reference/verifyage) + +### Table of contents +- [Backend flow](#backend-flow) + - [Authorization](#authorization) + - [API usage](#api-usage) +- [Frontend flow](#frontend-flow) + - [Authorization code request](#authorization-code-request) + - [Callback handling](#callback-handling) + +## Backend flow + +### Authorization + +```python Sample SDK for Python +from aggregator_opengateway_sdk import ClientCredentials, AgeVerifier + +credentials = ClientCredentials( + client_id='my-app-id', + client_secret='my-app-secret' +) + +age_client = AgeVerifier(credentials=credentials, phone_number='+34629255833') +``` + +```javascript HTTP using JavaScript (ES6) +let clientId = "my-app-id"; +let clientSecret = "my-app-secret"; +let appCredentials = btoa(`${clientId}:${clientSecret}`); +let scope = "dpv:FraudPreventionAndDetection kyc-age-verification:verify"; + +const tokenRequest = await fetch("https://opengateway.aggregator.com/token", { + method: "POST", + headers: { + "Content-Type": "application/x-www-form-urlencoded", + "Authorization": `Basic ${appCredentials}` + }, + body: new URLSearchParams({ scope }) +}); + +const { access_token } = await tokenRequest.json(); +``` + +### API usage + +```python Sample SDK for Python +result = age_client.verify_age({ + "ageThreshold": 18, + "idDocument": "12345678A", + "givenName": "Federica", + "familyName": "Sanchez", + "birthdate": "1990-05-12", + "email": "user@example.com", + "includeContentLock": True, + "includeParentalControl": True +}) + +print("Age check passed?", result.ageCheck) +print("Verified ID?", result.verifiedStatus) +print("Match score:", result.identityMatchScore) +print("Content lock:", result.contentLock) +print("Parental control:", result.parentalControl) +``` + +```javascript HTTP using JavaScript (ES6) +const headers = new Headers(); +headers.append("Authorization", `Bearer ${access_token}`); +headers.append("Content-Type", "application/json"); + +const payload = JSON.stringify({ + ageThreshold: 18, + idDocument: "12345678A", + givenName: "Federica", + familyName: "Sanchez", + birthdate: "1990-05-12", + email: "user@example.com", + includeContentLock: true, + includeParentalControl: true +}); + +const response = await fetch("https://opengateway.aggregator.com/kyc-age-verification/v0.1/verify", { + method: "POST", + headers, + body: payload +}); + +const result = await response.json(); +console.log("Age check:", result.ageCheck); +console.log("Verified status:", result.verifiedStatus); +console.log("Match score:", result.identityMatchScore); +``` + +--- + +## Frontend flow + +### Authorization code request + +```javascript HTTP using JavaScript (ES6) +let clientId = "my-app-id"; +let redirectUri = "https://myapp.com/age-callback"; +let scope = "dpv:FraudPreventionAndDetection kyc-age-verification:verify"; + +const params = new URLSearchParams({ + client_id: clientId, + response_type: "code", + scope, + redirect_uri: redirectUri +}); + +window.location.href = `https://opengateway.aggregator.com/authorize?${params.toString()}`; +``` + +### Callback handling + +```python HTTP using Python + Flask +from flask import Flask, request +import requests, base64 + +client_id = "my-app-id" +client_secret = "my-app-secret" + +app = Flask(__name__) + +@app.route('/age-callback', methods=['GET']) +def callback(): + code = request.args.get('code') + credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode() + headers = { + "Content-Type": "application/x-www-form-urlencoded", + "Authorization": f"Basic {credentials}" + } + data = { + "grant_type": "authorization_code", + "code": code, + "redirect_uri": "https://myapp.com/age-callback" + } + response = requests.post("https://opengateway.aggregator.com/token", headers=headers, data=data) + access_token = response.json().get("access_token") + return access_token + +if __name__ == '__main__': + app.run() diff --git a/v0/catalog/linetenure/line_tenure_openapi.yaml b/v0/catalog/linetenure/line_tenure_openapi.yaml new file mode 100644 index 0000000..82c82e0 --- /dev/null +++ b/v0/catalog/linetenure/line_tenure_openapi.yaml @@ -0,0 +1,289 @@ +openapi: 3.0.3 +info: + title: Tenure + termsOfService: http://swagger.io/terms/ + contact: + name: Telefónica Open Gateway DevRel + url: https://opengateway.telefonica.com/en/developer-hub + email: devrel@telefonica.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: "0.1" + +servers: + - url: "{host}/kyc-tenure/v0.1" + variables: + host: + default: sandbox.opengateway.telefonica.com/apigateway + description: API gateway URL + +tags: + - name: Check Subscriber Tenure + description: Check details about the length of tenure of the subscriber + +paths: + /check-tenure: + post: + summary: Check tenure length v0.1 + tags: + - Check Subscriber Tenure + description: | + Verifies a specified length of tenure, based on a provided date, for a network subscriber to establish a level of trust for the network subscription identifier. + + Check the [Authorization guide](/docs/authorization) on how to get an OAuth2 token, with the following scope: + + `dpv:FraudPreventionAndDetection#kyc-tenure` + + Create an app on our [Sandbox](/docs/sandbox) to get credentials and [retrieve tokens](/reference/authorize) so you can perform API calls to our operators' production environments, or use the following convenience token to test in mock mode: + + `mock_sandbox_access_token` + operationId: checkTenure + security: + - openId: + - kyc-tenure + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TenureRequest" + responses: + "200": + description: Respond with tenure information + headers: + x-correlator: + $ref: "#/components/headers/X-Correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/TenureInfo" + examples: + SUCCESS_RESPONSE: + value: + tenureDateCheck: true + contractType: "PAYM" + "400": + $ref: '#/components/responses/Generic400' + "401": + $ref: '#/components/responses/Generic401' + "403": + $ref: '#/components/responses/Generic403' + "404": + $ref: '#/components/responses/Generic404' + "422": + $ref: '#/components/responses/Generic422' + +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + description: Required scope: dpv:FraudPreventionAndDetection#kyc-tenure + + headers: + X-Correlator: + description: Correlation id for the different services + schema: + type: string + pattern: ^[a-zA-Z0-9-]{0,55}$ + + schemas: + TenureRequest: + description: Specifies date from which continuous tenure of the identified mobile subscriber is required to be confirmed + type: object + properties: + tenureDate: + type: string + description: The date, in RFC 3339 / ISO 8601 compliant format "YYYY-MM-DD", from which continuous tenure of the identified network subscriber is required to be confirmed + format: date + example: "2023-07-03" + phoneNumber: + type: string + description: The phone number in E.164 format to validate tenure. If not provided, it must be extracted from the access token context. + example: "+34629255833" + required: + - tenureDate + + TenureInfo: + type: object + properties: + tenureDateCheck: + description: | + `true` when the identified mobile subscription has had valid tenure since `tenureDate`, otherwise `false` + example: true + type: boolean + contractType: + description: | + If exists, populated with: + - `PAYG` - prepaid (pay-as-you-go) account + - `PAYM` - contract account + - `Business` - Business (enterprise) account + + This attribute may be omitted from the response set if the information is not available + example: "PAYM" + type: string + enum: ["PAYG", "PAYM", "Business"] + required: + - tenureDateCheck + + ErrorInfo: + type: object + required: + - message + - status + - code + properties: + message: + type: string + description: A human readable description of what the event represent + status: + type: integer + description: HTTP response status code + code: + type: string + description: Friendly Code to describe the error + + responses: + Generic400: + description: Bad Request + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + - OUT_OF_RANGE + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + + Generic401: + description: Unauthorized + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 401 + code: + enum: + - UNAUTHENTICATED + - AUTHENTICATION_REQUIRED + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + + Generic403: + description: Forbidden + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + + Generic404: + description: Not found + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 404 + code: + enum: + - IDENTIFIER_NOT_FOUND + examples: + GENERIC_404_IDENTIFIER_NOT_FOUND: + description: The phone number is not associated with a CSP customer account + value: + status: 404 + code: IDENTIFIER_NOT_FOUND + message: The phone number provided is not associated with a customer account + + Generic422: + description: Unprocessable Content + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 422 + code: + enum: + - SERVICE_NOT_APPLICABLE + - MISSING_IDENTIFIER + - UNNECESSARY_IDENTIFIER + examples: + GENERIC_422_SERVICE_NOT_APPLICABLE: + description: Service is not applicable for the provided phone number + value: + status: 422 + code: SERVICE_NOT_APPLICABLE + message: The service is not applicable for the provided phone number + GENERIC_422_MISSING_IDENTIFIER: + description: No phone number has been provided either explicitly or associated with the access token + value: + status: 422 + code: MISSING_IDENTIFIER + message: No phone number has been provided + GENERIC_422_UNNECESSARY_IDENTIFIER: + description: An explicit phone number has been provided when one is already associated with the access token + value: + status: 422 + code: UNNECESSARY_IDENTIFIER + message: An explicit phone number has been provided when one is already associated with the access token diff --git a/v0/catalog/linetenure/samplecode_linetenure.md b/v0/catalog/linetenure/samplecode_linetenure.md new file mode 100644 index 0000000..d51091e --- /dev/null +++ b/v0/catalog/linetenure/samplecode_linetenure.md @@ -0,0 +1,175 @@ +--- +title: Sample code for Tenure +excerpt: The following samples show how to use the [Open Gateway Tenure API](https://opengateway.telefonica.com/en/apis/tenure) to check whether a mobile subscription has been active since a given date, enabling fraud prevention and trust verification use cases. +category: 681879c3afc1a0003709c745 +--- + +The API consumption flow for Tenure follows the [OIDC Authorization Code Flow](https://github.com/camaraproject/IdentityAndConsentManagement/blob/release-0.1.0/documentation/CAMARA-API-access-and-user-consent.md#authorization-code-flow-frontend-flow). That means the request is triggered from the **frontend** (end-user device) but must be **completed on the backend**, where the access token is obtained and the API is called. + +> 📘 Want to try it before coding? +> Check the [API reference and live console](https://developers.opengateway.telefonica.com/reference/checktenure) + +## Table of contents +- [Frontend](#frontend) + - [Requesting the authorization code](#requesting-the-authorization-code) +- [Backend](#backend) + - [Getting the access token](#getting-the-access-token) + - [Calling the Tenure API](#calling-the-tenure-api) + +--- + +## Frontend + +The API flow starts from the **end-user's device**, such as a mobile phone: +- Your application requests user authorization with a `redirect_uri` to receive the `code`. +- After successful login/consent, the telco redirects back to your callback with the authorization `code`. + +### Requesting the authorization code +```javascript +let clientId = "my-app-id"; +let redirectUri = "https://my-backend.com/tenure-callback"; +let scope = "dpv:FraudPreventionAndDetection#kyc-tenure"; + +const params = new URLSearchParams({ + response_type: "code", + client_id: clientId, + redirect_uri: redirectUri, + scope: scope +}); + +window.location.href = `https://opengateway.aggregator.com/authorize?${params.toString()}`; +``` + +Or using an HTML form: +```html +
+ + + + + +
+``` + +--- + +## Backend + +After the frontend redirects to your `redirect_uri`, your backend receives the `code`, uses it to obtain an `access_token`, and then calls the API. + +### Getting the access token +#### Python +```python +import requests + +client_id = "my-app-id" +client_secret = "my-app-secret" +redirect_uri = "https://my-backend.com/tenure-callback" +code = "received-from-redirect" + +token = requests.post( + "https://opengateway.aggregator.com/token", + auth=(client_id, client_secret), + data={ + "grant_type": "authorization_code", + "code": code, + "redirect_uri": redirect_uri + } +) + +access_token = token.json()["access_token"] +``` + +#### Node.js +```javascript +const fetch = require('node-fetch'); +const btoa = require('btoa'); + +const clientId = "my-app-id"; +const clientSecret = "my-app-secret"; +const redirectUri = "https://my-backend.com/tenure-callback"; +const code = "received-from-redirect"; + +const credentials = btoa(`${clientId}:${clientSecret}`); + +fetch("https://opengateway.aggregator.com/token", { + method: "POST", + headers: { + "Authorization": `Basic ${credentials}`, + "Content-Type": "application/x-www-form-urlencoded" + }, + body: new URLSearchParams({ + grant_type: "authorization_code", + code: code, + redirect_uri: redirectUri + }) +}) +.then(res => res.json()) +.then(data => console.log(data.access_token)); +``` + +#### cURL +```bash +curl -X POST https://opengateway.aggregator.com/token \ + -u "my-app-id:my-app-secret" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=authorization_code&code=received-from-redirect&redirect_uri=https://my-backend.com/tenure-callback" +``` + +--- + +### Calling the Tenure API +#### Python +```python +headers = { + "Authorization": f"Bearer {access_token}", + "Content-Type": "application/json" +} + +data = { + "tenureDate": "2023-07-03" +} + +response = requests.post( + "https://sandbox.opengateway.telefonica.com/apigateway/kyc-tenure/v0.1/check-tenure", + headers=headers, + json=data +) + +print(response.json()) +``` + +#### Node.js +```javascript +const headers = { + "Authorization": `Bearer ${access_token}`, + "Content-Type": "application/json" +}; + +const body = JSON.stringify({ + tenureDate: "2023-07-03" +}); + +fetch("https://sandbox.opengateway.telefonica.com/apigateway/kyc-tenure/v0.1/check-tenure", { + method: "POST", + headers, + body +}) + .then(res => res.json()) + .then(result => console.log(result)); +``` + +#### cURL +```bash +curl -X POST https://sandbox.opengateway.telefonica.com/apigateway/kyc-tenure/v0.1/check-tenure \ + -H "Authorization: Bearer $ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"tenureDate": "2023-07-03"}' +``` + +--- + +## Notes +- Replace `my-app-id` and `my-app-secret` with your own credentials. +- Register and manage your apps at the [Open Gateway Sandbox](https://sandbox.opengateway.telefonica.com/my-apps). +- You can use `mock_sandbox_access_token` for testing. \ No newline at end of file diff --git a/v0/catalog/scamsignal/scam_signal_openapi.yaml b/v0/catalog/scamsignal/scam_signal_openapi.yaml new file mode 100644 index 0000000..c4936d5 --- /dev/null +++ b/v0/catalog/scamsignal/scam_signal_openapi.yaml @@ -0,0 +1,51 @@ +openapi: 3.0.3 +info: + title: Scam Signal + version: "0.1" + termsOfService: https://opengateway.telefonica.com/en/terms + contact: + name: Telefónica Open Gateway DevRel + url: https://opengateway.telefonica.com/en/developer-hub + email: devrel@telefonica.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + +servers: + - url: "{host}/scam-signal/v0.1" + variables: + host: + default: sandbox.opengateway.telefonica.com/apigateway + description: API gateway URL + +tags: + - name: Detect active scams + description: Trigger real-time telco-based intelligence to identify potential fraud during critical customer actions. + +paths: + /detect: + post: + summary: Scam Signal v0.1 (confidential parameters) + tags: + - Detect active scams + description: | + The Scam Signal API is designed to help prevent scams in real-time by offering a telecom-powered risk signal. This allows businesses to: + + - Pause suspicious payment attempts + - Trigger customer verification flows + - Reduce false positives in fraud scoring systems + + It has proven to reduce fraud losses and improve user safety in sensitive flows such as online banking and high-value transactions. + + **Note:** Due to the sensitive nature of this API, parameters and schema are not publicly disclosed. + + Key business use cases include: + - Preventing real-time payment scams (e.g. APP fraud) + - Adding telecom signals to existing fraud detection models + - Improving protection in SME/corporate transaction platforms + + For access to integration details and onboarding support, **get in touch with our API experts** through the following link: + + 👉 [Talk to an expert now](https://opengateway.telefonica.com/en/contactexpert) to explore how Scam Signal can protect your users in real-time. + +