Add Forward API client and request handling for forwarding API requests

src/CheckoutSdk/CheckoutApi.cs

@@ -5,6 +5,7 @@
 using Checkout.Disputes;
 using Checkout.Financial;
 using Checkout.Forex;
+using Checkout.Forward;
 using Checkout.Instruments;
 using Checkout.Metadata;
 using Checkout.Payments;
@@ -43,6 +44,7 @@
         private readonly IIssuingClient _issuingClient;
         private readonly IPaymentContextsClient _paymentContextsClient;
         private readonly IPaymentSessionsClient _paymentSessionsClient;
+        private readonly IForwardClient _forwardClient;
 
         public CheckoutApi(CheckoutConfiguration configuration)
         {
@@ -72,6 +74,7 @@
             _issuingClient = new IssuingClient(baseApiClient, configuration);
             _paymentContextsClient = new PaymentContextsClient(baseApiClient, configuration);
             _paymentSessionsClient = new PaymentSessionsClient(baseApiClient, configuration);
+            _forwardClient = new ForwardClient(baseApiClient, configuration);
         }
 
         private static ApiClient BaseApiClient(CheckoutConfiguration configuration)
@@ -130,7 +133,7 @@
             return _disputesClient;
         }
 
         public IRiskClient RiskClient()
         {
             return _riskClient;
         }
@@ -204,5 +207,10 @@
         {
             return _paymentSessionsClient;
         }
+
+        public IForwardClient ForwardClient()
+        {
+            return _forwardClient;
+        }
     }
 }

src/CheckoutSdk/Forward/ForwardClient.cs

@@ -0,0 +1,41 @@
+using Checkout.Forward.Requests;
+using Checkout.Forward.Responses;
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Checkout.Forward
+{
+    public class ForwardClient : AbstractClient, IForwardClient
+    {
+        private const string Forward = "forward";
+
+        public ForwardClient(IApiClient apiClient, CheckoutConfiguration configuration) :
+            base(apiClient, configuration, SdkAuthorizationType.SecretKeyOrOAuth)
+        {
+        }
+
+        public Task<ForwardAnApiResponse> ForwardAnApiRequest(ForwardRequest forwardRequest,
+            CancellationToken cancellationToken = default)
+        {
+            CheckoutUtils.ValidateParams("forwardRequest", forwardRequest);
+            return ApiClient.Post<ForwardAnApiResponse>(
+                Forward,
+                SdkAuthorization(),
+                forwardRequest,
+                cancellationToken
+            );
+        }
+
+        public Task<GetForwardResponse> GetForwardRequest(string forwardId,
+            CancellationToken cancellationToken = default)
+        {
+            CheckoutUtils.ValidateParams("forwardId", forwardId);
+            return ApiClient.Get<GetForwardResponse>(
+                BuildPath(Forward, forwardId),
+                SdkAuthorization(),
+                cancellationToken
+            );
+        }
+    }
+}

src/CheckoutSdk/Forward/IForwardClient.cs

@@ -0,0 +1,26 @@
+using Checkout.Forward.Requests;
+using Checkout.Forward.Responses;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Checkout.Forward
+{
+    public interface IForwardClient
+    {
+        /// <summary>
+        ///     Forward an API request<br />
+        ///     <b>Beta</b><br />
+        ///     Forwards an API request to a third-party endpoint.<br />
+        ///     For example, you can forward payment credentials you've stored in our Vault to a third-party payment processor.
+        /// </summary>
+        Task<ForwardAnApiResponse> ForwardAnApiRequest(ForwardRequest forwardRequest,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        ///     Get forward request<br />
+        ///     Retrieve the details of a successfully forwarded API request.<br />
+        ///     The details can be retrieved for up to 14 days after the request was initiated.
+        /// </summary>
+        Task<GetForwardResponse> GetForwardRequest(string forwardId, CancellationToken cancellationToken = default);
+    }
+}

src/CheckoutSdk/Forward/Requests/DestinationRequest.cs

@@ -0,0 +1,21 @@
+namespace Checkout.Forward.Requests
+{
+    public class DestinationRequest
+    {
+        /// <summary>
+        ///     The URL to forward the request to (Required, max 1024 characters) </summary>
+        public string Url { get; set; }
+
+        /// <summary> The HTTP method to use for the forward request (Required) </summary>
+        public MethodType Method { get; set; }
+
+        /// <summary> The HTTP headers to include in the forward request (Required) </summary>
+        public Headers Headers { get; set; }
+
+        /// <summary>
+        ///     The HTTP message body to include in the forward request. If you provide source.id or source.token, you can specify
+        ///     placeholder values in the body. The request will be enriched with the respective payment details from the token or
+        ///     payment instrument you specified. For example, {{card_number}} (Required, max 16384 characters) </summary>
+        public string Body { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Requests/ForwardRequest.cs

@@ -0,0 +1,30 @@
+using Checkout.Forward.Requests.Sources;
+
+namespace Checkout.Forward.Requests
+{
+    public class ForwardRequest
+    {
+        /// <summary>
+        ///     The payment source to enrich the forward request with. You can provide placeholder values in
+        ///     destination_request.body. The request will be enriched with the respective payment credentials from the token or
+        ///     payment instrument you specified. For example, {{card_number}} (Required)
+        /// </summary>
+        public AbstractSource Source { get; set; }
+
+        /// <summary> The parameters of the forward request (Required) </summary>
+        public DestinationRequest DestinationRequest { get; set; }
+
+        /// <summary>
+        ///     The unique reference for the forward request (Optional, max 80 characters) </summary>
+        public string Reference { get; set; }
+
+        /// <summary>
+        ///     The processing channel ID to associate the billing for the forward request with (Optional, 
+        ///     pattern ^(pc)_(\w{26})$)
+        /// </summary>
+        public string ProcessingChannelId { get; set; }
+
+        /// <summary> Specifies if and how a network token should be used in the forward request (Optional) </summary>
+        public NetworkToken NetworkToken { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Requests/Headers.cs

@@ -0,0 +1,16 @@
+using System.Collections.Generic;
+
+namespace Checkout.Forward.Requests
+{
+    public class Headers
+    {
+        /// <summary>
+        ///     The raw headers to include in the forward request (Required, max 16 characters) </summary>
+        public IDictionary<string, string> Raw { get; set; } = new Dictionary<string, string>();
+
+        /// <summary>
+        ///     The encrypted headers to include in the forward request, as a JSON object with string values encrypted with JSON
+        ///     Web Encryption (JWE) (Optional, max 8192 characters) </summary>
+        public string Encrypted { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Requests/MethodType.cs

@@ -0,0 +1,23 @@
+using System.Runtime.Serialization;
+
+namespace Checkout.Forward.Requests
+{
+    public enum MethodType
+    {
+        [EnumMember(Value = "GET")] Get,
+
+        [EnumMember(Value = "POST")] Post,
+
+        [EnumMember(Value = "PUT")] Put,
+
+        [EnumMember(Value = "DELETE")] Delete,
+
+        [EnumMember(Value = "PATCH")] Patch,
+
+        [EnumMember(Value = "HEAD")] Head,
+
+        [EnumMember(Value = "OPTIONS")] Options,
+
+        [EnumMember(Value = "TRACE")] Trace
+    }
+}

src/CheckoutSdk/Forward/Requests/NetworkToken.cs

@@ -0,0 +1,14 @@
+namespace Checkout.Forward.Requests
+{
+    public class NetworkToken
+    {
+        /// <summary> Specifies whether to use a network token (Optional) </summary>
+        public bool? Enabled { get; set; }
+
+        /// <summary>
+        ///     Specifies whether to generate a cryptogram. For example, for customer-initiated transactions (CITs). If you
+        ///     set network_token.enabled to true, you must provide this field (Optional)
+        /// </summary>
+        public bool? RequestCryptogram { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Requests/Sources/AbstractSource.cs

@@ -0,0 +1,10 @@
+namespace Checkout.Forward.Requests.Sources
+{
+    public abstract class AbstractSource
+    {
+        protected AbstractSource(SourceType type) { Type = type; }
+
+        /// <summary> The payment source type (Required) </summary>
+        public SourceType? Type { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Requests/Sources/IdSource.cs

@@ -0,0 +1,19 @@
+namespace Checkout.Forward.Requests.Sources
+{
+    public class IdSource : AbstractSource
+    {
+        /// <summary>Initializes a new instance of the IdSource class.</summary>
+        public IdSource() : base(SourceType.Id) { }
+
+        /// <summary> The unique identifier of the payment instrument (Required, pattern ^(src)_(\w{26})$) </summary>
+        public string Id { get; set; }
+
+        /// <summary>
+        ///     The unique token for the card's security code. Checkout.com does not store a card's Card Verification Value
+        ///     (CVV) with its associated payment instrument. To pass a CVV with your forward request, use the Frames SDK for
+        ///     Android or iOS to collect and tokenize the CVV and pass the value in this field. The token will replace the
+        ///     placeholder {{card_cvv}} value in destination_request.body (Optional, pattern ^(tok)_(\w{26})$)
+        /// </summary>
+        public string CvvToken { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Requests/Sources/SourceType.cs

@@ -0,0 +1,11 @@
+using System.Runtime.Serialization;
+
+namespace Checkout.Forward.Requests.Sources
+{
+    public enum SourceType
+    {
+        [EnumMember(Value = "id")] Id,
+
+        [EnumMember(Value = "token")] Token
+    }
+}

src/CheckoutSdk/Forward/Requests/Sources/TokenSource.cs

@@ -0,0 +1,11 @@
+namespace Checkout.Forward.Requests.Sources
+{
+    public class TokenSource : AbstractSource
+    {
+        /// <summary>Initializes a new instance of the TokenSource class.</summary>
+        public TokenSource() : base(SourceType.Token) { }
+
+        /// <summary> The unique Checkout.com token (Required, pattern ^(tok)_(\w{26})$) </summary>
+        public string Token { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Responses/DestinationRequest.cs

@@ -0,0 +1,22 @@
+using System.Collections.Generic;
+
+namespace Checkout.Forward.Responses
+{
+    public class DestinationRequest
+    {
+        /// <summary> The URL of the forward request (Required) </summary>
+        public string Url { get; set; }
+
+        /// <summary> The HTTP method of the forward request (Required) </summary>
+        public string Method { get; set; }
+
+        /// <summary> The HTTP headers of the forward request. Encrypted and sensitive header values are redacted (Required) </summary>
+        public IDictionary<string, string> Headers { get; set; } = new Dictionary<string, string>();
+
+        /// <summary>
+        ///     The HTTP message body of the forward request. This is the original value used to initiate the request, with
+        ///     placeholder value text included. For example, {{card_number}} is not replaced with an actual card number (Required)
+        /// </summary>
+        public string Body { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Responses/DestinationResponse.cs

@@ -0,0 +1,16 @@
+using System.Collections.Generic;
+
+namespace Checkout.Forward.Responses
+{
+    public class DestinationResponse
+    {
+        /// <summary> The HTTP status code of the destination response (Required) </summary>
+        public int Status { get; set; }
+
+        /// <summary> The destination response's HTTP headers. (Required) </summary>
+        public IDictionary<string, IList<string>> Headers { get; set; } = new Dictionary<string, IList<string>>();
+
+        /// <summary> The destination response's HTTP message body (Required) </summary>
+        public string Body { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Responses/ForwardAnApiResponse.cs

@@ -0,0 +1,14 @@
+namespace Checkout.Forward.Responses
+{
+    public class ForwardAnApiResponse : HttpMetadata
+    {
+        /// <summary> The unique identifier for the forward request (Required) </summary>
+        public string RequestId { get; set; }
+
+        /// <summary>
+        ///     The HTTP response received from the destination, if the forward request completed successfully. Sensitive PCI
+        ///     data will be removed from the response (Optional)
+        /// </summary>
+        public DestinationResponse DestinationResponse { get; set; }
+    }
+}

src/CheckoutSdk/Forward/Responses/GetForwardResponse.cs

@@ -0,0 +1,30 @@
+using System;
+
+namespace Checkout.Forward.Responses
+{
+    public class GetForwardResponse : HttpMetadata
+    {
+        /// <summary> The unique identifier for the forward request (Required) </summary>
+        public string RequestId { get; set; }
+
+        /// <summary> The client entity linked to the forward request (Required) </summary>
+        public string EntityId { get; set; }
+
+        /// <summary> The parameters of the HTTP request forwarded to the destination (Required) </summary>
+        public DestinationRequest DestinationRequest { get; set; }
+
+        /// <summary>
+        ///     The date and time the forward request was created, in UTC (Required)
+        /// </summary>
+        public DateTime? CreatedOn { get; set; }
+
+        /// <summary> The unique reference for the forward request (Optional) </summary>
+        public string Reference { get; set; }
+
+        /// <summary>
+        ///     The HTTP response received from the destination. Sensitive PCI data is not included in the response
+        ///     (Optional)
+        /// </summary>
+        public DestinationResponse DestinationResponse { get; set; }
+    }
+}

src/CheckoutSdk/ICheckoutApi.cs

@@ -5,6 +5,7 @@
 using Checkout.Disputes;
 using Checkout.Financial;
 using Checkout.Forex;
+using Checkout.Forward;
 using Checkout.Instruments;
 using Checkout.Metadata;
 using Checkout.Payments;
@@ -33,7 +34,7 @@
 
         IDisputesClient DisputesClient();
 
         IRiskClient RiskClient();
 
         IForexClient ForexClient();
 
@@ -62,5 +63,7 @@
         IPaymentContextsClient PaymentContextsClient();
 
         IPaymentSessionsClient PaymentSessionsClient();
+
+        IForwardClient ForwardClient();
     }
 }

src/CheckoutSdk/OAuthScope.cs

@@ -50,5 +50,6 @@ public enum OAuthScope
         [OAuthScope("issuing:controls-write")] IssuingControlWrite,
         [OAuthScope("issuing:transactions-read")] IssuingTransactionsRead,
         [OAuthScope("Payment Context")] PaymentContext,
+        [OAuthScope("forward")] Forward,
     }
 }